npm - @cubis/foundry - Versions diffs - 0.3.71 → 0.3.72 - Mend

@cubis/foundry 0.3.71 → 0.3.72

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (270) hide show

package/workflows/powers/api-patterns/POWER.md CHANGED Viewed

@@ -2,82 +2,68 @@
 ---
 inclusion: manual
 name: api-patterns
-description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # API Patterns
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
+## Purpose
-## 🎯 Selective Reading Rule
+Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy.
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When to Use
----
+- Choosing REST vs GraphQL vs type-safe RPC for a new surface.
+- Standardizing response envelopes, pagination, filtering, and error format.
+- Planning auth, rate limits, and evolution strategy for an API surface.
+- Reviewing whether an API design matches client and organizational constraints.
-## 📑 Content Map
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
-| `response.md` | Envelope pattern, error format, pagination | Response structure |
-| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
-| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
-| `versioning.md` | URI/Header/Query versioning | API evolution planning |
-| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| `rate-limiting.md` | Token bucket, sliding window | API protection |
-| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
-| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+## Instructions
----
+1. Clarify clients, latency needs, ownership model, and compatibility constraints.
+2. Choose transport shape based on product and team context, not habit.
+3. Standardize response and error patterns before implementation fans out.
+4. Define pagination, filtering, and auth strategy explicitly.
+5. Make versioning and operational protections part of the design, not an afterthought.
-## 🔗 Related Skills
+### Baseline standards
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
+- Use one consistent response and error vocabulary per API surface.
+- Prefer explicit evolution strategy over “we will figure it out later.”
+- Match the pattern to client needs and team capability.
+- Treat rate limiting and abuse controls as part of API design.
+- Keep auth semantics visible and documented.
----
+### Constraints
-## ✅ Decision Checklist
+- Avoid defaulting to REST, GraphQL, or RPC by trend alone.
+- Avoid inconsistent envelopes across related endpoints.
+- Avoid mixing public and internal conventions into one confused surface.
+- Avoid delaying versioning and pagination decisions until after rollout.
-Before designing an API:
+## Output Format
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
----
+## References
-## ❌ Anti-Patterns
+Load on demand. Do not preload all reference files.
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
+| File | Load when |
+| --- | --- |
+| `references/pattern-selection-checklist.md` | You need a sharper decision aid for REST vs GraphQL vs RPC, response envelopes, auth shape, and versioning tradeoffs. |
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
+## Scripts
----
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
-## Script
+## Examples
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+- "Help me with api patterns best practices in this project"
+- "Review my api patterns implementation for issues"
 ````

package/workflows/powers/api-patterns/SKILL.md CHANGED Viewed

@@ -1,81 +1,66 @@
 ---
 name: api-patterns
-description: API design principles and decision-making. REST vs GraphQL vs tRPC selection, response formats, versioning, pagination.
-allowed-tools: Read, Write, Edit, Glob, Grep
+description: "Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # API Patterns
-> API design principles and decision-making for 2025.
-> **Learn to THINK, not copy fixed patterns.**
+## Purpose
-## 🎯 Selective Reading Rule
+Use when choosing between REST, GraphQL, and type-safe RPC patterns, or when standardizing response envelopes, versioning, pagination, auth shape, and API protection strategy.
-**Read ONLY files relevant to the request!** Check the content map, find what you need.
+## When to Use
----
-## 📑 Content Map
-| File | Description | When to Read |
-|------|-------------|--------------|
-| `api-style.md` | REST vs GraphQL vs tRPC decision tree | Choosing API type |
-| `rest.md` | Resource naming, HTTP methods, status codes | Designing REST API |
-| `response.md` | Envelope pattern, error format, pagination | Response structure |
-| `graphql.md` | Schema design, when to use, security | Considering GraphQL |
-| `trpc.md` | TypeScript monorepo, type safety | TS fullstack projects |
-| `versioning.md` | URI/Header/Query versioning | API evolution planning |
-| `auth.md` | JWT, OAuth, Passkey, API Keys | Auth pattern selection |
-| `rate-limiting.md` | Token bucket, sliding window | API protection |
-| `documentation.md` | OpenAPI/Swagger best practices | Documentation |
-| `security-testing.md` | OWASP API Top 10, auth/authz testing | Security audits |
+- Choosing REST vs GraphQL vs type-safe RPC for a new surface.
+- Standardizing response envelopes, pagination, filtering, and error format.
+- Planning auth, rate limits, and evolution strategy for an API surface.
+- Reviewing whether an API design matches client and organizational constraints.
----
+## Instructions
-## 🔗 Related Skills
+1. Clarify clients, latency needs, ownership model, and compatibility constraints.
+2. Choose transport shape based on product and team context, not habit.
+3. Standardize response and error patterns before implementation fans out.
+4. Define pagination, filtering, and auth strategy explicitly.
+5. Make versioning and operational protections part of the design, not an afterthought.
-| Need | Skill |
-|------|-------|
-| API implementation | `@[skills/backend-development]` |
-| Data structure | `@[skills/database-design]` |
-| Security details | `@[skills/security-hardening]` |
+### Baseline standards
----
+- Use one consistent response and error vocabulary per API surface.
+- Prefer explicit evolution strategy over “we will figure it out later.”
+- Match the pattern to client needs and team capability.
+- Treat rate limiting and abuse controls as part of API design.
+- Keep auth semantics visible and documented.
-## ✅ Decision Checklist
+### Constraints
-Before designing an API:
+- Avoid defaulting to REST, GraphQL, or RPC by trend alone.
+- Avoid inconsistent envelopes across related endpoints.
+- Avoid mixing public and internal conventions into one confused surface.
+- Avoid delaying versioning and pagination decisions until after rollout.
-- [ ] **Asked user about API consumers?**
-- [ ] **Chosen API style for THIS context?** (REST/GraphQL/tRPC)
-- [ ] **Defined consistent response format?**
-- [ ] **Planned versioning strategy?**
-- [ ] **Considered authentication needs?**
-- [ ] **Planned rate limiting?**
-- [ ] **Documentation approach defined?**
+## Output Format
----
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
-## ❌ Anti-Patterns
+## References
-**DON'T:**
-- Default to REST for everything
-- Use verbs in REST endpoints (/getUsers)
-- Return inconsistent response formats
-- Expose internal errors to clients
-- Skip rate limiting
+Load on demand. Do not preload all reference files.
-**DO:**
-- Choose API style based on context
-- Ask about client requirements
-- Document thoroughly
-- Use appropriate status codes
+| File | Load when |
+| --- | --- |
+| `references/pattern-selection-checklist.md` | You need a sharper decision aid for REST vs GraphQL vs RPC, response envelopes, auth shape, and versioning tradeoffs. |
----
+## Scripts
-## Script
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
-| Script | Purpose | Command |
-|--------|---------|---------|
-| `scripts/api_validator.py` | API endpoint validation | `python scripts/api_validator.py <project_path>` |
+## Examples
+- "Help me with api patterns best practices in this project"
+- "Review my api patterns implementation for issues"

package/workflows/powers/architecture-designer/POWER.md CHANGED Viewed

@@ -1,86 +1,69 @@
 ````markdown
 ---
 inclusion: manual
-name: "architecture-designer"
-description: "Use when designing new system architecture, reviewing existing designs, or making architectural decisions. Invoke for system design, architecture review, design patterns, ADRs, scalability planning."
+name: architecture-designer
+description: "Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # Architecture Designer
-## Overview
-Senior software architect specializing in system design, design patterns, and architectural decision-making.
-## Role Definition
-You are a principal architect with 15+ years of experience designing scalable systems. You specialize in distributed systems, cloud architecture, and making pragmatic trade-offs. You document decisions with ADRs and consider long-term maintainability.
-## When to Use This Skill
+## Purpose
-- Designing new system architecture
-- Choosing between architectural patterns
-- Reviewing existing architecture
-- Creating Architecture Decision Records (ADRs)
-- Planning for scalability
-- Evaluating technology choices
+Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform.
-## Core Workflow
+## When to Use
-1. **Understand requirements** - Functional, non-functional, constraints
-2. **Identify patterns** - Match requirements to architectural patterns
-3. **Design** - Create architecture with trade-offs documented
-4. **Document** - Write ADRs for key decisions
-5. **Review** - Validate with stakeholders
+- Designing a new system or reshaping an existing one.
+- Making boundary, ownership, integration, or deployment tradeoffs explicit.
+- Writing or reviewing architectural decisions and ADR-style reasoning.
+- Deciding how much architecture is actually justified for the product stage.
-## Available Steering Files
+## Instructions
-Load detailed guidance on-demand:
+1. Clarify product goals, constraints, and failure tolerance.
+2. Identify the few architectural decisions that materially change risk or cost.
+3. Compare viable shapes and document tradeoffs, not just the favorite option.
+4. Choose the smallest architecture that safely supports the current target.
+5. Hand off explicit boundaries, risks, and follow-up validation points.
-| Topic                 | Reference                           | Load When                             |
-| --------------------- | ----------------------------------- | ------------------------------------- |
-| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices    |
-| ADR Template          | `references/adr-template.md`          | Documenting decisions                 |
-| System Design         | `references/system-design.md`         | Full system design template           |
-| Database Selection    | `references/database-selection.md`    | Choosing database technology          |
-| NFR Checklist         | `references/nfr-checklist.md`         | Gathering non-functional requirements |
+### Baseline standards
-## Constraints
+- Start from product outcomes, not architecture fashion.
+- Make ownership and interfaces explicit.
+- Consider security, observability, and operations as part of the design.
+- Prefer reversible decisions when uncertainty is high.
+- Keep ADR-style reasoning concrete and testable.
-### MUST DO
+### Constraints
-- Document all significant decisions with ADRs
-- Consider non-functional requirements explicitly
-- Evaluate trade-offs, not just benefits
-- Plan for failure modes
-- Consider operational complexity
-- Review with stakeholders before finalizing
+- Avoid over-engineering for hypothetical future scale.
+- Avoid treating diagrams as a substitute for boundary decisions.
+- Avoid choosing technology before identifying the real constraints.
+- Avoid hiding unresolved risk behind vague architectural language.
-### MUST NOT DO
+## Output Format
-- Over-engineer for hypothetical scale
-- Choose technology without evaluating alternatives
-- Ignore operational costs
-- Design without understanding requirements
-- Skip security considerations
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
-## Output Templates
+## References
-When designing architecture, provide:
+Load on demand. Do not preload all reference files.
-1. Requirements summary (functional + non-functional)
-2. High-level architecture diagram
-3. Key decisions with trade-offs (ADR format)
-4. Technology recommendations with rationale
-5. Risks and mitigation strategies
+| File | Load when |
+| --- | --- |
+| `references/system-tradeoff-checklist.md` | You need a sharper system-design checklist for boundaries, ADRs, integration shape, resilience, and rollout risk. |
-## Knowledge Reference
+## Scripts
-Distributed systems, microservices, event-driven architecture, CQRS, DDD, CAP theorem, cloud platforms (AWS, GCP, Azure), containers, Kubernetes, message queues, caching, database design
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
-## Related Powers
+## Examples
-- **Fullstack Guardian** - Implementing designs
-- **DevOps Engineer** - Infrastructure implementation
-- **Secure Code Guardian** - Security architecture
+- "Help me with architecture designer best practices in this project"
+- "Review my architecture designer implementation for issues"
 ````

package/workflows/powers/architecture-designer/SKILL.md CHANGED Viewed

@@ -1,83 +1,66 @@
 ---
-name: "architecture-designer"
-description: "Use when designing new system architecture, reviewing existing designs, or making architectural decisions. Invoke for system design, architecture review, design patterns, ADRs, scalability planning."
+name: architecture-designer
+description: "Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform."
+license: MIT
+metadata:
+  author: cubis-foundry
+  version: "3.0"
+compatibility: Claude Code, Codex, GitHub Copilot
 ---
 # Architecture Designer
-## Overview
-Senior software architect specializing in system design, design patterns, and architectural decision-making.
-## Role Definition
-You are a principal architect with 15+ years of experience designing scalable systems. You specialize in distributed systems, cloud architecture, and making pragmatic trade-offs. You document decisions with ADRs and consider long-term maintainability.
-## When to Use This Skill
+## Purpose
-- Designing new system architecture
-- Choosing between architectural patterns
-- Reviewing existing architecture
-- Creating Architecture Decision Records (ADRs)
-- Planning for scalability
-- Evaluating technology choices
+Use when designing or reviewing system architecture, interface boundaries, tradeoffs, ADRs, scalability posture, and the smallest durable target shape for a product or platform.
-## Core Workflow
+## When to Use
-1. **Understand requirements** - Functional, non-functional, constraints
-2. **Identify patterns** - Match requirements to architectural patterns
-3. **Design** - Create architecture with trade-offs documented
-4. **Document** - Write ADRs for key decisions
-5. **Review** - Validate with stakeholders
+- Designing a new system or reshaping an existing one.
+- Making boundary, ownership, integration, or deployment tradeoffs explicit.
+- Writing or reviewing architectural decisions and ADR-style reasoning.
+- Deciding how much architecture is actually justified for the product stage.
-## Available Steering Files
+## Instructions
-Load detailed guidance on-demand:
+1. Clarify product goals, constraints, and failure tolerance.
+2. Identify the few architectural decisions that materially change risk or cost.
+3. Compare viable shapes and document tradeoffs, not just the favorite option.
+4. Choose the smallest architecture that safely supports the current target.
+5. Hand off explicit boundaries, risks, and follow-up validation points.
-| Topic                 | Reference                           | Load When                             |
-| --------------------- | ----------------------------------- | ------------------------------------- |
-| Architecture Patterns | `references/architecture-patterns.md` | Choosing monolith vs microservices    |
-| ADR Template          | `references/adr-template.md`          | Documenting decisions                 |
-| System Design         | `references/system-design.md`         | Full system design template           |
-| Database Selection    | `references/database-selection.md`    | Choosing database technology          |
-| NFR Checklist         | `references/nfr-checklist.md`         | Gathering non-functional requirements |
+### Baseline standards
-## Constraints
+- Start from product outcomes, not architecture fashion.
+- Make ownership and interfaces explicit.
+- Consider security, observability, and operations as part of the design.
+- Prefer reversible decisions when uncertainty is high.
+- Keep ADR-style reasoning concrete and testable.
-### MUST DO
+### Constraints
-- Document all significant decisions with ADRs
-- Consider non-functional requirements explicitly
-- Evaluate trade-offs, not just benefits
-- Plan for failure modes
-- Consider operational complexity
-- Review with stakeholders before finalizing
+- Avoid over-engineering for hypothetical future scale.
+- Avoid treating diagrams as a substitute for boundary decisions.
+- Avoid choosing technology before identifying the real constraints.
+- Avoid hiding unresolved risk behind vague architectural language.
-### MUST NOT DO
+## Output Format
-- Over-engineer for hypothetical scale
-- Choose technology without evaluating alternatives
-- Ignore operational costs
-- Design without understanding requirements
-- Skip security considerations
+Provide implementation guidance, code examples, and configuration as appropriate to the task.
-## Output Templates
+## References
-When designing architecture, provide:
+Load on demand. Do not preload all reference files.
-1. Requirements summary (functional + non-functional)
-2. High-level architecture diagram
-3. Key decisions with trade-offs (ADR format)
-4. Technology recommendations with rationale
-5. Risks and mitigation strategies
+| File | Load when |
+| --- | --- |
+| `references/system-tradeoff-checklist.md` | You need a sharper system-design checklist for boundaries, ADRs, integration shape, resilience, and rollout risk. |
-## Knowledge Reference
+## Scripts
-Distributed systems, microservices, event-driven architecture, CQRS, DDD, CAP theorem, cloud platforms (AWS, GCP, Azure), containers, Kubernetes, message queues, caching, database design
+No helper scripts are required for this skill right now. Keep execution in `SKILL.md` and `references/` unless repeated automation becomes necessary.
-## Related Powers
+## Examples
-- **Fullstack Guardian** - Implementing designs
-- **DevOps Engineer** - Infrastructure implementation
-- **Secure Code Guardian** - Security architecture
+- "Help me with architecture designer best practices in this project"
+- "Review my architecture designer implementation for issues"

package/workflows/powers/ask-questions-if-underspecified/POWER.md CHANGED Viewed

@@ -2,18 +2,28 @@
 ---
 inclusion: manual
 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
@@ -24,6 +34,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)
@@ -38,6 +49,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)
@@ -49,10 +61,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
@@ -85,4 +99,38 @@ 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."
 ````