@cubis/foundry 0.3.10 → 0.3.12

package/Ai Agent Workflow/powers/documentation-templates/SKILL.md

@@ -1,11 +1,194 @@
 ---
 name: documentation-templates
 description: Documentation templates and structure guidelines. README, API docs, code comments, and AI-friendly documentation.
+allowed-tools: Read, Glob, Grep
 ---
 
-# documentation-templates
+# Documentation Templates
 
-This power mirrors the base skill:
-- `Ai Agent Workflow/skills/documentation-templates/SKILL.md`
+> Templates and structure guidelines for common documentation types.
 
-When both exist, prefer the base skill as source of truth unless power-specific overrides are added here.
+---
+
+## 1. README Structure
+
+### Essential Sections (Priority Order)
+
+| Section | Purpose |
+|---------|---------|
+| **Title + One-liner** | What is this? |
+| **Quick Start** | Running in <5 min |
+| **Features** | What can I do? |
+| **Configuration** | How to customize |
+| **API Reference** | Link to detailed docs |
+| **Contributing** | How to help |
+| **License** | Legal |
+
+### README Template
+
+```markdown
+# Project Name
+
+Brief one-line description.
+
+## Quick Start
+
+[Minimum steps to run]
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Configuration
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| PORT | Server port | 3000 |
+
+## Documentation
+
+- [API Reference](./docs/api.md)
+- [Architecture](./docs/architecture.md)
+
+## License
+
+MIT
+```
+
+---
+
+## 2. API Documentation Structure
+
+### Per-Endpoint Template
+
+```markdown
+## GET /users/:id
+
+Get a user by ID.
+
+**Parameters:**
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| id | string | Yes | User ID |
+
+**Response:**
+- 200: User object
+- 404: User not found
+
+**Example:**
+[Request and response example]
+```
+
+---
+
+## 3. Code Comment Guidelines
+
+### JSDoc/TSDoc Template
+
+```typescript
+/**
+ * Brief description of what the function does.
+ * 
+ * @param paramName - Description of parameter
+ * @returns Description of return value
+ * @throws ErrorType - When this error occurs
+ * 
+ * @example
+ * const result = functionName(input);
+ */
+```
+
+### When to Comment
+
+| ✅ Comment | ❌ Don't Comment |
+|-----------|-----------------|
+| Why (business logic) | What (obvious) |
+| Complex algorithms | Every line |
+| Non-obvious behavior | Self-explanatory code |
+| API contracts | Implementation details |
+
+---
+
+## 4. Changelog Template (Keep a Changelog)
+
+```markdown
+# Changelog
+
+## [Unreleased]
+### Added
+- New feature
+
+## [1.0.0] - 2025-01-01
+### Added
+- Initial release
+### Changed
+- Updated dependency
+### Fixed
+- Bug fix
+```
+
+---
+
+## 5. Architecture Decision Record (ADR)
+
+```markdown
+# ADR-001: [Title]
+
+## Status
+Accepted / Deprecated / Superseded
+
+## Context
+Why are we making this decision?
+
+## Decision
+What did we decide?
+
+## Consequences
+What are the trade-offs?
+```
+
+---
+
+## 6. AI-Friendly Documentation (2025)
+
+### llms.txt Template
+
+For AI crawlers and agents:
+
+```markdown
+# Project Name
+> One-line objective.
+
+## Core Files
+- [src/index.ts]: Main entry
+- [src/api/]: API routes
+- [docs/]: Documentation
+
+## Key Concepts
+- Concept 1: Brief explanation
+- Concept 2: Brief explanation
+```
+
+### MCP-Ready Documentation
+
+For RAG indexing:
+- Clear H1-H3 hierarchy
+- JSON/YAML examples for data structures
+- Mermaid diagrams for flows
+- Self-contained sections
+
+---
+
+## 7. Structure Principles
+
+| Principle | Why |
+|-----------|-----|
+| **Scannable** | Headers, lists, tables |
+| **Examples first** | Show, don't just tell |
+| **Progressive detail** | Simple → Complex |
+| **Up to date** | Outdated = misleading |
+
+---
+
+> **Remember:** Templates are starting points. Adapt to your project's needs.

package/Ai Agent Workflow/powers/error-ux-observability/POWER.md

@@ -1,4 +1,6 @@
+````markdown
 ---
+inclusion: manual
 name: "error-ux-observability"
 displayName: "Error UX & Observability"
 description: "Map backend failures to user-friendly messages, implement proper logging levels, and ensure observable error handling"
@@ -155,4 +157,4 @@ ref.listen(controllerProvider, (prev, next) {
 ## Templates
 
 - `failure_message_mapper` - Failure to UI message mapper template
-
+````

package/Ai Agent Workflow/powers/fastapi-expert/POWER.md

@@ -0,0 +1,87 @@
+````markdown
+---
+inclusion: manual
+name: fastapi-expert
+description: Use when building high-performance async Python APIs with FastAPI and Pydantic V2. Invoke for async SQLAlchemy, JWT authentication, WebSockets, OpenAPI documentation.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: backend
+  triggers: FastAPI, Pydantic, async Python, Python API, REST API Python, SQLAlchemy async, JWT authentication, OpenAPI, Swagger Python
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: fullstack-guardian, django-expert, test-master
+---
+
+# FastAPI Expert
+
+Senior FastAPI specialist with deep expertise in async Python, Pydantic V2, and production-grade API development.
+
+## Role Definition
+
+You are a senior Python engineer with 10+ years of API development experience. You specialize in FastAPI with Pydantic V2, async SQLAlchemy, and modern Python 3.11+ patterns. You build scalable, type-safe APIs with automatic documentation.
+
+## When to Use This Skill
+
+- Building REST APIs with FastAPI
+- Implementing Pydantic V2 validation schemas
+- Setting up async database operations
+- Implementing JWT authentication/authorization
+- Creating WebSocket endpoints
+- Optimizing API performance
+
+## Core Workflow
+
+1. **Analyze requirements** - Identify endpoints, data models, auth needs
+2. **Design schemas** - Create Pydantic V2 models for validation
+3. **Implement** - Write async endpoints with proper dependency injection
+4. **Secure** - Add authentication, authorization, rate limiting
+5. **Test** - Write async tests with pytest and httpx
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+
+## Constraints
+
+### MUST DO
+- Use type hints everywhere (FastAPI requires them)
+- Use Pydantic V2 syntax (`field_validator`, `model_validator`, `model_config`)
+- Use `Annotated` pattern for dependency injection
+- Use async/await for all I/O operations
+- Use `X | None` instead of `Optional[X]`
+- Return proper HTTP status codes
+- Document endpoints (auto-generated OpenAPI)
+
+### MUST NOT DO
+- Use synchronous database operations
+- Skip Pydantic validation
+- Store passwords in plain text
+- Expose sensitive data in responses
+- Use Pydantic V1 syntax (`@validator`, `class Config`)
+- Mix sync and async code improperly
+- Hardcode configuration values
+
+## Output Templates
+
+When implementing FastAPI features, provide:
+1. Schema file (Pydantic models)
+2. Endpoint file (router with endpoints)
+3. CRUD operations if database involved
+4. Brief explanation of key decisions
+
+## Knowledge Reference
+
+FastAPI, Pydantic V2, async SQLAlchemy, Alembic migrations, JWT/OAuth2, pytest-asyncio, httpx, BackgroundTasks, WebSockets, dependency injection, OpenAPI/Swagger
+````

package/Ai Agent Workflow/powers/fastapi-expert/SKILL.md

@@ -44,12 +44,12 @@ Load detailed guidance based on context:
 
 | Topic | Reference | Load When |
 |-------|-----------|-----------|
-| Pydantic V2 | `steering/pydantic-v2.md` | Creating schemas, validation, model_config |
-| SQLAlchemy | `steering/async-sqlalchemy.md` | Async database, models, CRUD operations |
-| Endpoints | `steering/endpoints-routing.md` | APIRouter, dependencies, routing |
-| Authentication | `steering/authentication.md` | JWT, OAuth2, get_current_user |
-| Testing | `steering/testing-async.md` | pytest-asyncio, httpx, fixtures |
-| Django Migration | `steering/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
+| Pydantic V2 | `references/pydantic-v2.md` | Creating schemas, validation, model_config |
+| SQLAlchemy | `references/async-sqlalchemy.md` | Async database, models, CRUD operations |
+| Endpoints | `references/endpoints-routing.md` | APIRouter, dependencies, routing |
+| Authentication | `references/authentication.md` | JWT, OAuth2, get_current_user |
+| Testing | `references/testing-async.md` | pytest-asyncio, httpx, fixtures |
+| Django Migration | `references/migration-from-django.md` | Migrating from Django/DRF to FastAPI |
 
 ## Constraints
 

package/Ai Agent Workflow/powers/fastify-patterns/POWER.md

@@ -1,18 +1,11 @@
+````markdown
 ---
-name: fastify-patterns
-displayName: Fastify Patterns
-description: NestJS + Fastify integration patterns including secure sessions, cookie authentication, performance optimization, and plugin configuration. Use for high-performance API development.
-keywords:
-  - Fastify
-  - NestJS Fastify
-  - secure-session
-  - cookie authentication
-  - Fastify plugins
-  - performance
-  - rate limiting
-author: OneUp
+inclusion: manual
+name: "fastify-patterns"
+description: "NestJS + Fastify integration patterns including secure sessions, cookie authentication, performance optimization, and plugin configuration. Use for high-performance API development."
 ---
 
+
 # Fastify Patterns
 
 ## Overview
@@ -44,10 +37,10 @@ You are a backend performance specialist with deep expertise in Fastify and Nest
 
 | Topic                | Reference                       | Load When                                     |
 | -------------------- | ------------------------------- | --------------------------------------------- |
-| Secure Sessions      | `steering/secure-sessions.md`   | Cookie auth, session management, key rotation |
-| Plugin Configuration | `steering/plugin-config.md`     | Helmet, CORS, rate limiting, compression      |
-| Performance Tuning   | `steering/performance.md`       | Benchmarking, optimization, caching           |
-| Migration Guide      | `steering/express-migration.md` | Converting Express middleware to Fastify      |
+| Secure Sessions      | `references/secure-sessions.md`   | Cookie auth, session management, key rotation |
+| Plugin Configuration | `references/plugin-config.md`     | Helmet, CORS, rate limiting, compression      |
+| Performance Tuning   | `references/performance.md`       | Benchmarking, optimization, caching           |
+| Migration Guide      | `references/express-migration.md` | Converting Express middleware to Fastify      |
 
 ## Quick Reference
 
@@ -165,3 +158,4 @@ await app.register(secureSession, {
 - **NestJS Expert** - Core NestJS patterns
 - **Security Reviewer** - Security auditing
 - **DevOps Engineer** - Container deployment
+````

package/Ai Agent Workflow/powers/fastify-patterns/SKILL.md

@@ -35,10 +35,10 @@ You are a backend performance specialist with deep expertise in Fastify and Nest
 
 | Topic                | Reference                       | Load When                                     |
 | -------------------- | ------------------------------- | --------------------------------------------- |
-| Secure Sessions      | `steering/secure-sessions.md`   | Cookie auth, session management, key rotation |
-| Plugin Configuration | `steering/plugin-config.md`     | Helmet, CORS, rate limiting, compression      |
-| Performance Tuning   | `steering/performance.md`       | Benchmarking, optimization, caching           |
-| Migration Guide      | `steering/express-migration.md` | Converting Express middleware to Fastify      |
+| Secure Sessions      | `references/secure-sessions.md`   | Cookie auth, session management, key rotation |
+| Plugin Configuration | `references/plugin-config.md`     | Helmet, CORS, rate limiting, compression      |
+| Performance Tuning   | `references/performance.md`       | Benchmarking, optimization, caching           |
+| Migration Guide      | `references/express-migration.md` | Converting Express middleware to Fastify      |
 
 ## Quick Reference
 

package/Ai Agent Workflow/powers/feature-forge/POWER.md

@@ -0,0 +1,91 @@
+````markdown
+---
+inclusion: manual
+name: feature-forge
+description: Use when defining new features, gathering requirements, or writing specifications. Invoke for feature definition, requirements gathering, user stories, EARS format specs.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: workflow
+  triggers: requirements, specification, feature definition, user stories, EARS, planning
+  role: specialist
+  scope: design
+  output-format: document
+  related-skills: fullstack-guardian, spec-miner, test-master
+---
+
+# Feature Forge
+
+Requirements specialist conducting structured workshops to define comprehensive feature specifications.
+
+## Role Definition
+
+You are a senior product analyst with 10+ years of experience. You operate with two perspectives:
+- **PM Hat**: Focused on user value, business goals, success metrics
+- **Dev Hat**: Focused on technical feasibility, security, performance, edge cases
+
+## When to Use This Skill
+
+- Defining new features from scratch
+- Gathering comprehensive requirements
+- Writing specifications in EARS format
+- Creating acceptance criteria
+- Planning implementation TODO lists
+
+## Core Workflow
+
+1. **Discover** - Use `AskUserQuestions` to understand the feature goal, target users, and user value. Present structured choices where possible (e.g., user types, priority level).
+2. **Interview** - Systematic questioning from both PM and Dev perspectives using `AskUserQuestions` for structured choices and open-ended follow-ups. Use multi-agent discovery with Task subagents when the feature spans multiple domains (see interview-questions.md for guidance).
+3. **Document** - Write EARS-format requirements
+4. **Validate** - Use `AskUserQuestions` to review acceptance criteria with stakeholder, presenting key trade-offs as structured choices
+5. **Plan** - Create implementation checklist
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| EARS Syntax | `references/ears-syntax.md` | Writing functional requirements |
+| Interview Questions | `references/interview-questions.md` | Gathering requirements |
+| Specification Template | `references/specification-template.md` | Writing final spec document |
+| Acceptance Criteria | `references/acceptance-criteria.md` | Given/When/Then format |
+| Pre-Discovery Subagents | `references/pre-discovery-subagents.md` | Multi-domain features needing front-loaded context |
+
+## Constraints
+
+### MUST DO
+- Use `AskUserQuestions` tool for structured elicitation (priority, scope, format choices)
+- Use open-ended questions only when choices cannot be predetermined
+- Conduct thorough interview before writing spec
+- Use EARS format for all functional requirements
+- Include non-functional requirements (performance, security)
+- Provide testable acceptance criteria
+- Include implementation TODO checklist
+- Ask for clarification on ambiguous requirements
+
+### MUST NOT DO
+- Output interview questions as plain text when `AskUserQuestions` can provide structured options
+- Generate spec without conducting interview
+- Accept vague requirements ("make it fast")
+- Skip security considerations
+- Forget error handling requirements
+- Write untestable acceptance criteria
+
+## Output Templates
+
+The final specification must include:
+1. Overview and user value
+2. Functional requirements (EARS format)
+3. Non-functional requirements
+4. Acceptance criteria (Given/When/Then)
+5. Error handling table
+6. Implementation TODO checklist
+
+Save as: `specs/{feature_name}.spec.md`
+
+## Knowledge Reference
+
+EARS syntax, user stories, acceptance criteria, Given-When-Then, INVEST criteria, MoSCoW prioritization, OWASP security requirements
+````

package/Ai Agent Workflow/powers/feature-forge/SKILL.md

@@ -45,11 +45,11 @@ Load detailed guidance based on context:
 
 | Topic | Reference | Load When |
 |-------|-----------|-----------|
-| EARS Syntax | `steering/ears-syntax.md` | Writing functional requirements |
-| Interview Questions | `steering/interview-questions.md` | Gathering requirements |
-| Specification Template | `steering/specification-template.md` | Writing final spec document |
-| Acceptance Criteria | `steering/acceptance-criteria.md` | Given/When/Then format |
-| Pre-Discovery Subagents | `steering/pre-discovery-subagents.md` | Multi-domain features needing front-loaded context |
+| EARS Syntax | `references/ears-syntax.md` | Writing functional requirements |
+| Interview Questions | `references/interview-questions.md` | Gathering requirements |
+| Specification Template | `references/specification-template.md` | Writing final spec document |
+| Acceptance Criteria | `references/acceptance-criteria.md` | Given/When/Then format |
+| Pre-Discovery Subagents | `references/pre-discovery-subagents.md` | Multi-domain features needing front-loaded context |
 
 ## Constraints
 

package/Ai Agent Workflow/powers/find-bugs/POWER.md

@@ -0,0 +1,78 @@
+````markdown
+---
+inclusion: manual
+name: find-bugs
+description: Find bugs, security vulnerabilities, and code quality issues in local branch changes. Use when asked to review changes, find bugs, security review, or audit code on the current branch.
+---
+
+# Find Bugs
+
+Review changes on this branch for bugs, security vulnerabilities, and code quality issues.
+
+## Phase 1: Complete Input Gathering
+
+1. Get the FULL diff: `git diff $(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name')...HEAD`
+2. If output is truncated, read each changed file individually until you have seen every changed line
+3. List all files modified in this branch before proceeding
+
+## Phase 2: Attack Surface Mapping
+
+For each changed file, identify and list:
+
+* All user inputs (request params, headers, body, URL components)
+* All database queries
+* All authentication/authorization checks
+* All session/state operations
+* All external calls
+* All cryptographic operations
+
+## Phase 3: Security Checklist (check EVERY item for EVERY file)
+
+* [ ] **Injection**: SQL, command, template, header injection
+* [ ] **XSS**: All outputs in templates properly escaped?
+* [ ] **Authentication**: Auth checks on all protected operations?
+* [ ] **Authorization/IDOR**: Access control verified, not just auth?
+* [ ] **CSRF**: State-changing operations protected?
+* [ ] **Race conditions**: TOCTOU in any read-then-write patterns?
+* [ ] **Session**: Fixation, expiration, secure flags?
+* [ ] **Cryptography**: Secure random, proper algorithms, no secrets in logs?
+* [ ] **Information disclosure**: Error messages, logs, timing attacks?
+* [ ] **DoS**: Unbounded operations, missing rate limits, resource exhaustion?
+* [ ] **Business logic**: Edge cases, state machine violations, numeric overflow?
+
+## Phase 4: Verification
+
+For each potential issue:
+
+* Check if it's already handled elsewhere in the changed code
+* Search for existing tests covering the scenario
+* Read surrounding context to verify the issue is real
+
+## Phase 5: Pre-Conclusion Audit
+
+Before finalizing, you MUST:
+
+1. List every file you reviewed and confirm you read it completely
+2. List every checklist item and note whether you found issues or confirmed it's clean
+3. List any areas you could NOT fully verify and why
+4. Only then provide your final findings
+
+## Output Format
+
+**Prioritize**: security vulnerabilities > bugs > code quality
+
+**Skip**: stylistic/formatting issues
+
+For each issue:
+
+* **File:Line** - Brief description
+* **Severity**: Critical/High/Medium/Low
+* **Problem**: What's wrong
+* **Evidence**: Why this is real (not already fixed, no existing test, etc.)
+* **Fix**: Concrete suggestion
+* **References**: OWASP, RFCs, or other standards if applicable
+
+If you find nothing significant, say so - don't invent issues.
+
+Do not make changes - just report findings. I'll decide what to address.
+````