devstack 0.1.0

package/vendor/skills/skills/lesson-learned/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: lesson-learned
+description: "Analyze recent code changes via git history and extract software engineering lessons. Use when the user asks 'what is the lesson here?', 'what can I learn from this?', 'engineering takeaway', 'what did I just learn?', 'reflect on this code', or wants to extract principles from recent work."
+---
+
+# Lesson Learned
+
+Extract specific, grounded software engineering lessons from actual code changes. Not a lecture -- a mirror. Show the user what their code already demonstrates.
+
+## Before You Begin
+
+**Load the principles reference first.**
+
+1. Read `references/se-principles.md` to have the principle catalog available
+2. Optionally read `references/anti-patterns.md` if you suspect the changes include areas for improvement
+3. Determine the scope of analysis (see Phase 1)
+
+**Do not proceed until you've loaded at least `se-principles.md`.**
+
+## Phase 1: Determine Scope
+
+Ask the user or infer from context what to analyze.
+
+| Scope           | Git Commands                                            | When to Use                                             |
+| --------------- | ------------------------------------------------------- | ------------------------------------------------------- |
+| Feature branch  | `git log main..HEAD --oneline` + `git diff main...HEAD` | User is on a non-main branch (default)                  |
+| Last N commits  | `git log --oneline -N` + `git diff HEAD~N..HEAD`        | User specifies a range, or on main (default N=5)        |
+| Specific commit | `git show <sha>`                                        | User references a specific commit                       |
+| Working changes | `git diff` + `git diff --cached`                        | User says "what about these changes?" before committing |
+
+**Default behavior:**
+
+- If on a feature branch: analyze branch commits vs main
+- If on main: analyze the last 5 commits
+- If the user provides a different scope, use that
+
+## Phase 2: Gather Changes
+
+1. Run `git log` with the determined scope to get the commit list and messages
+2. Run `git diff` for the full diff of the scope
+3. If the diff is large (>500 lines), use `git diff --stat` first, then selectively read the top 3-5 most-changed files
+4. **Read commit messages carefully** -- they contain intent that raw diffs miss
+5. Only read changed files. Do not read the entire repo.
+
+## Phase 3: Analyze
+
+Identify the **dominant pattern** -- the single most instructive thing about these changes.
+
+Look for:
+
+- **Structural decisions** -- How was the code organized? Why those boundaries?
+- **Trade-offs made** -- What was gained vs. sacrificed? (readability vs. performance, DRY vs. clarity, speed vs. correctness)
+- **Problems solved** -- What was the before/after? What made the "after" better?
+- **Missed opportunities** -- Where could the code improve? (present gently as "next time, consider...")
+
+Map findings to specific principles from `references/se-principles.md`. Be specific -- quote actual code, reference actual file names and line changes.
+
+## Phase 4: Present the Lesson
+
+Use this template:
+
+```markdown
+## Lesson: [Principle Name]
+
+**What happened in the code:**
+[2-3 sentences describing the specific change, referencing files and commits]
+
+**The principle at work:**
+[1-2 sentences explaining the SE principle]
+
+**Why it matters:**
+[1-2 sentences on the practical consequence -- what would go wrong without this, or what goes right because of it]
+
+**Takeaway for next time:**
+[One concrete, actionable sentence the user can apply to future work]
+```
+
+If there is a second lesson worth noting (maximum 2 additional):
+
+```markdown
+---
+
+### Also worth noting: [Principle Name]
+
+**In the code:** [1 sentence]
+**The principle:** [1 sentence]
+**Takeaway:** [1 sentence]
+```
+
+## What NOT to Do
+
+| Avoid                                        | Why                                 | Instead                                         |
+| -------------------------------------------- | ----------------------------------- | ----------------------------------------------- |
+| Listing every principle that vaguely applies | Overwhelming and generic            | Pick the 1-2 most relevant                      |
+| Analyzing files that were not changed        | Scope creep                         | Stick to the diff                               |
+| Ignoring commit messages                     | They contain intent that diffs miss | Read them as primary context                    |
+| Abstract advice disconnected from the code   | Not actionable                      | Always reference specific files/lines           |
+| Negative-only feedback                       | Demoralizing                        | Lead with what works, then suggest improvements |
+| More than 3 lessons                          | Dilutes the insight                 | One well-grounded lesson beats seven vague ones |
+
+## Conversation Style
+
+- **Reflective, not prescriptive.** Use the user's own code as primary evidence.
+- **Never say "you should have..."** -- instead use "the approach here shows..." or "next time you face this, consider..."
+- **If the code is good, say so.** Not every lesson is about what went wrong. Recognizing good patterns reinforces them.
+- **If the changes are trivial** (a single config tweak, a typo fix), say so honestly rather than forcing a lesson. "These changes are straightforward -- no deep lesson here, just good housekeeping."
+- **Be specific.** Generic advice is worthless. Every claim must point to a concrete code change.

package/vendor/skills/skills/lesson-learned/references/anti-patterns.md

@@ -0,0 +1,55 @@
+---
+description: Common anti-patterns to detect in code diffs. Use alongside se-principles.md for balanced analysis -- principles show what's good, anti-patterns show what to watch for.
+---
+
+# Anti-Patterns
+
+When analyzing a diff, check for these signals. Present findings gently -- as opportunities, not failures.
+
+## God Object / God Class
+
+One module doing too much.
+**Diff signals:** A single file with many unrelated changes. One class/module imported everywhere. A file over 500 lines that keeps growing.
+**Suggest:** Extract responsibilities into focused modules (SRP).
+
+## Shotgun Surgery
+
+One logical change scattered across many files.
+**Diff signals:** 10+ files changed for a single feature or fix. The same type of edit repeated in many places. A rename or config change touching dozens of files.
+**Suggest:** Consolidate the scattered logic. If one change requires editing many files, the abstraction boundaries may be wrong.
+
+## Feature Envy
+
+A function that uses another module's data more than its own.
+**Diff signals:** Heavy cross-module imports. A function reaching deep into another object's properties. Utility functions that only serve one caller in a different module.
+**Suggest:** Move the function closer to the data it uses.
+
+## Premature Abstraction
+
+Abstracting before there are multiple concrete cases.
+**Diff signals:** An interface with exactly one implementation. A factory that creates only one type. A generic solution for a problem that exists only once.
+**Suggest:** Wait for the second or third use case before abstracting (Rule of Three).
+
+## Copy-Paste Programming
+
+Duplicated code blocks with minor variations.
+**Diff signals:** Similar code appearing in multiple places in the diff. Functions that differ by only a parameter or two. Repeated patterns that could be parameterized.
+**Suggest:** Extract shared logic, parameterize the differences.
+
+## Magic Numbers / Strings
+
+Literal values without explanation.
+**Diff signals:** Hardcoded numbers in conditions (`if (retries > 3)`). String literals used as keys or identifiers. Timeouts, limits, or thresholds without named constants.
+**Suggest:** Extract to named constants that explain the "why."
+
+## Long Method
+
+Functions that do too much.
+**Diff signals:** New functions over 40-50 lines. Functions with multiple levels of nesting. Functions that require scrolling to read.
+**Suggest:** Extract sub-steps into named functions. Each function should do one thing.
+
+## Excessive Comments
+
+Comments explaining "what" instead of "why."
+**Diff signals:** Comments restating the code (`// increment counter`). Large comment blocks before straightforward code. Commented-out code left in place.
+**Suggest:** Make the code self-documenting through better naming. Use comments only for "why" -- intent, trade-offs, non-obvious constraints.

package/vendor/skills/skills/lesson-learned/references/se-principles.md

@@ -0,0 +1,109 @@
+---
+description: Curated catalog of software engineering principles. Load this before analyzing code changes so you can map observations to named principles.
+---
+
+# Software Engineering Principles
+
+Use this as a lookup table. When you spot a pattern in a diff, find the matching principle here. Each entry includes **code signals** -- what to look for in actual changes.
+
+## Design Principles (SOLID)
+
+**Single Responsibility Principle (SRP)**
+A module should have one reason to change.
+Code signals: A class/file was split into two. A function was extracted. A component stopped handling both UI and data fetching.
+
+**Open/Closed Principle (OCP)**
+Open for extension, closed for modification.
+Code signals: New behavior added without changing existing code. A plugin/hook/callback system introduced. Strategy pattern or configuration used instead of conditionals.
+
+**Liskov Substitution Principle (LSP)**
+Subtypes must be substitutable for their base types.
+Code signals: An interface was introduced to unify implementations. A subclass override changed behavior in a way that broke callers (violation). Type narrowing or guards added.
+
+**Interface Segregation Principle (ISP)**
+No client should depend on methods it doesn't use.
+Code signals: A large interface was split into smaller ones. Optional methods removed from an interface. A "fat" props object was broken into focused ones.
+
+**Dependency Inversion Principle (DIP)**
+Depend on abstractions, not concretions.
+Code signals: A concrete dependency replaced with an interface/injection. A factory or provider pattern introduced. Import paths changed from specific implementations to abstract layers.
+
+**Composition over Inheritance**
+Favor object composition over class inheritance.
+Code signals: Inheritance hierarchy replaced with delegation. Mixins or HOCs replaced with hooks or composition. A "base class" was removed.
+
+## Simplicity Principles
+
+**DRY (Don't Repeat Yourself)**
+Every piece of knowledge should have a single representation.
+Code signals: Duplicate code extracted into a shared function. A constant replaced repeated literals. A template/generator replaced copy-pasted boilerplate.
+
+**KISS (Keep It Simple, Stupid)**
+The simplest solution that works is the best.
+Code signals: A complex abstraction replaced with a straightforward implementation. Unnecessary indirection removed. A clever one-liner replaced with readable code.
+
+**YAGNI (You Aren't Gonna Need It)**
+Don't build it until you actually need it.
+Code signals: Speculative features removed. Unused configuration options deleted. An over-engineered solution simplified to match actual requirements.
+
+**Rule of Three**
+Wait until the third duplication before abstracting.
+Code signals: Similar code exists in 2 places and was left alone (good). A premature abstraction was introduced after only one use (violation). Third occurrence triggered extraction (textbook application).
+
+**Principle of Least Surprise**
+Code should behave the way most users would expect.
+Code signals: A function renamed to better describe what it does. Return types made consistent. Side effects made explicit or removed.
+
+## Structural Principles
+
+**Separation of Concerns**
+Different responsibilities should live in different modules.
+Code signals: Business logic extracted from UI components. Data access separated from domain logic. Configuration separated from behavior. A "god file" split into focused modules.
+
+**High Cohesion**
+Related functionality should live together.
+Code signals: Scattered related functions gathered into one module. A utility file broken up so each piece lives near its consumers. A feature folder created.
+
+**Loose Coupling**
+Modules should depend on each other as little as possible.
+Code signals: Direct imports replaced with events/callbacks. A shared dependency removed. Modules communicate through well-defined interfaces instead of reaching into internals.
+
+**Encapsulation**
+Hide internal details, expose only what's necessary.
+Code signals: Public methods reduced. Internal helpers made private. A module's API surface shrunk. Implementation details hidden behind a facade.
+
+**Information Hiding**
+Modules should not expose their internal data structures.
+Code signals: Raw data structures wrapped in accessor methods. Internal state made private. A data transformation moved inside the module that owns the data.
+
+## Pragmatic Principles
+
+**Boy Scout Rule**
+Leave the code better than you found it.
+Code signals: Small cleanups alongside a feature change. A renamed variable for clarity. A dead code path removed. An outdated comment updated.
+
+**Fail Fast**
+Detect and report errors as early as possible.
+Code signals: Input validation added at entry points. Assertions added for invariants. Early returns replacing deep nesting. Error handling moved closer to the source.
+
+**Defensive Programming**
+Anticipate and handle unexpected inputs gracefully.
+Code signals: Null checks added. Default values provided. Edge cases handled. Error boundaries introduced.
+
+**Premature Optimization (avoiding it)**
+Don't optimize until you've measured.
+Code signals: A simple implementation chosen over a "faster" complex one. Readability prioritized over micro-performance. A profiling step added before optimization work.
+
+## Refactoring Patterns
+
+**Extract Method/Function**
+Code signals: A long function split into named sub-functions. Inline logic replaced with a well-named call.
+
+**Extract Class/Module**
+Code signals: A file split into multiple files. A class split into two with distinct responsibilities.
+
+**Replace Conditional with Polymorphism**
+Code signals: A switch/if-else chain replaced with a strategy pattern or subclass dispatch. A type map introduced.
+
+**Introduce Parameter Object**
+Code signals: Multiple related parameters grouped into a single options/config object. Function signatures simplified.

package/vendor/skills/skills/mastra/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: mastra
+description: "Comprehensive Mastra framework guide. Teaches how to find current documentation, verify API signatures, and build agents and workflows. Covers documentation lookup strategies (embedded docs, remote docs), core concepts (agents vs workflows, tools, memory, RAG), TypeScript requirements, and common patterns. Use this skill for all Mastra development to ensure you're using current APIs from the installed version or latest documentation."
+license: Apache-2.0
+metadata:
+  author: Mastra
+  version: "2.0.0"
+  repository: https://github.com/mastra-ai/skills
+---
+
+# Mastra Framework Guide
+
+Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.
+
+## ⚠️ Critical: Do not trust internal knowledge
+
+Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.
+
+Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.
+
+## Prerequisites
+
+Before writing any Mastra code, check if packages are installed:
+
+```bash
+ls node_modules/@mastra/
+```
+
+- **If packages exist:** Use embedded docs first (most reliable)
+- **If no packages:** Install first or use remote docs
+
+## Documentation lookup guide
+
+### Quick Reference
+
+| User Question                       | First Check                                                      | How To                                         |
+| ----------------------------------- | ---------------------------------------------------------------- | ---------------------------------------------- |
+| "Create/install Mastra project"     | [`references/create-mastra.md`](references/create-mastra.md)     | Setup guide with CLI and manual steps          |
+| "How do I use Agent/Workflow/Tool?" | [`references/embedded-docs.md`](references/embedded-docs.md)     | Look up in `node_modules/@mastra/*/dist/docs/` |
+| "How do I use X?" (no packages)     | [`references/remote-docs.md`](references/remote-docs.md)         | Fetch from `https://mastra.ai/llms.txt`        |
+| "I'm getting an error..."           | [`references/common-errors.md`](references/common-errors.md)     | Common errors and solutions                    |
+| "Upgrade from v0.x to v1.x"         | [`references/migration-guide.md`](references/migration-guide.md) | Version upgrade workflows                      |
+
+### Priority order for writing code
+
+⚠️ Never write code without checking current docs first.
+
+1. **Embedded docs first** (if packages installed)
+
+   Look up current docs in `node_modules` for a package. Example of looking up "Agent" docs in `@mastra/core`:
+
+   ```bash
+   grep -r "Agent" node_modules/@mastra/core/dist/docs/references
+   ```
+
+   - **Why:** Matches your EXACT installed version
+   - **Most reliable source of truth**
+   - **See:** [`references/embedded-docs.md`](references/embedded-docs.md)
+
+2. **Source code second** (if packages installed)
+
+   If you can't find what you need in the embedded docs, look directly at the source code. This is more time consuming but can provide insights into implementation details.
+
+   ```bash
+   # Check what's available
+   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
+
+   # Read the actual type definition
+   cat node_modules/@mastra/core/dist/[path-from-source-map]
+   ```
+
+   - **Why:** Ultimate source of truth if docs are missing or unclear
+   - **Use when:** Embedded docs don't cover your question
+   - **See:** [`references/embedded-docs.md`](references/embedded-docs.md)
+
+3. **Remote docs third** (if packages not installed)
+
+   You can fetch the latest docs from the Mastra website:
+
+   ```bash
+   https://mastra.ai/llms.txt
+   ```
+
+   - **Why:** Latest published docs (may be ahead of installed version)
+   - **Use when:** Packages not installed or exploring new features
+   - **See:** [`references/remote-docs.md`](references/remote-docs.md)
+
+## Core concepts
+
+### Agents vs workflows
+
+**Agent**: Autonomous, makes decisions, uses tools
+Use for: Open-ended tasks (support, research, analysis)
+
+**Workflow**: Structured sequence of steps
+Use for: Defined processes (pipelines, approvals, ETL)
+
+### Key components
+
+- **Tools**: Extend agent capabilities (APIs, databases, external services)
+- **Memory**: Maintain context (message history, working memory, semantic recall)
+- **RAG**: Query external knowledge (vector stores, graph relationships)
+- **Storage**: Persist data (Postgres, LibSQL, MongoDB)
+
+## Critical requirements
+
+### TypeScript config
+
+Mastra requires **ES2022 modules**. CommonJS will fail.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+### Model format
+
+Always use `"provider/model-name"`:
+
+- `"openai/gpt-5.2"`
+- `"anthropic/claude-sonnet-4-5"`
+- `"google/gemini-2.5-pro"`
+
+## When you see errors
+
+**Type errors often mean your knowledge is outdated.**
+
+**Common signs of outdated knowledge:**
+
+- `Property X does not exist on type Y`
+- `Cannot find module`
+- `Type mismatch` errors
+- Constructor parameter errors
+
+**What to do:**
+
+1. Check [`references/common-errors.md`](references/common-errors.md)
+2. Verify current API in embedded docs
+3. Don't assume the error is a user mistake - it might be your outdated knowledge
+
+## Development workflow
+
+**Always verify before writing code:**
+
+1. **Check packages installed**
+
+   ```bash
+   ls node_modules/@mastra/
+   ```
+
+2. **Look up current API**
+   - If installed → Use embedded docs [`references/embedded-docs.md`](references/embedded-docs.md)
+   - If not → Use remote docs [`references/remote-docs.md`](references/remote-docs.md)
+
+3. **Write code based on current docs**
+
+4. **Test in Studio**
+   ```bash
+   npm run dev  # http://localhost:4111
+   ```
+
+## Resources
+
+- **Setup**: [`references/create-mastra.md`](references/create-mastra.md)
+- **Embedded docs lookup**: [`references/embedded-docs.md`](references/embedded-docs.md) - Start here if packages are installed
+- **Remote docs lookup**: [`references/remote-docs.md`](references/remote-docs.md)
+- **Common errors**: [`references/common-errors.md`](references/common-errors.md)
+- **Migrations**: [`references/migration-guide.md`](references/migration-guide.md)