sublation-os 1.0.2 → 1.1.0

package/.cursor/commands/sublation-os/learn.md

@@ -0,0 +1,131 @@
+---
+description: Append a new learning entry to categorized memory files so it can be reloaded by the agent for future reasoning
+model: sonnet
+---
+
+You are capturing a learning moment from the current session to help future Claude sessions work more effectively on this codebase.
+
+## Your Task
+
+Analyze the recent conversation context and generate a structured learning entry. Focus on:
+
+1. **What went wrong or required correction** (if applicable)
+2. **What pattern or practice should be followed**
+3. **Codebase-specific insights** (architecture, conventions, gotchas)
+4. **Tool usage patterns** that worked well or should be avoided
+
+## Step 1: Determine Category
+
+First, determine which category this learning belongs to:
+
+- **backend** - APIs, databases, services, server-side logic, data access
+- **frontend** - UI components, state management, user interactions, styling
+- **testing** - Testing strategies, frameworks, mocking, test organization
+- **architecture** - System design, patterns, project structure, cross-cutting concerns
+- **general** - Workflow, tooling, debugging, anything that doesn't fit above
+
+The target file will be: `.sublation-os/memory/{category}-lessons.md`
+
+## Entry Format
+
+Generate the entry in this exact format:
+
+```markdown
+## Entry {N} - {YYYY-MM-DD HH:mm}
+
+### 🧠 Context
+{1-2 sentences: What happened? What was the task or correction?}
+
+### 📘 Lesson
+{Core principle or insight as a durable rule. Be specific to this codebase when possible.}
+
+### ⚙️ Application
+{How should this affect future reasoning? Be actionable and specific. Include:
+- Which files/services/patterns this applies to
+- What to check before making similar changes
+- What tools or approaches work best}
+
+### 🧩 Example
+{OPTIONAL: Concrete before/after or do/don't example}
+
+### 🏷️ Tags
+{Comma-separated tags for searchability: e.g., "Work service, bulk operations, async patterns, testing"}
+
+---
+
+```
+
+## Instructions
+
+1. **Read the existing file** (if it exists) to:
+   - Determine the next entry number
+   - Ensure consistent formatting
+   - Avoid duplicate lessons
+
+2. **Generate the entry** with:
+   - Current timestamp in format: YYYY-MM-DD HH:mm
+   - Specific references to files, services, or patterns
+   - Tags for easy searching (service names, patterns, concepts)
+
+3. **Append to file**: `.sublation-os/memory/{category}-lessons.md`
+   - The file should already exist with a template header
+   - Append the new entry at the end of the file
+   - Ensure proper spacing between entries
+
+4. **Update index** (optional): If adding significant new tags or this is a notable learning, you may update `.sublation-os/memory/index.md` to add the new tags to the tag index
+
+5. **Confirm to user**:
+   - Show the generated entry
+   - Mention the category, entry number, and file location
+   - Suggest when this learning might be relevant
+
+## File Header (if creating new file)
+
+```markdown
+# Learned Lessons
+
+This file contains durable learnings from Claude Code sessions to help future sessions work more effectively on this codebase.
+
+**Search tips:**
+- Use Ctrl+F to find specific services or patterns
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+```
+
+## Quality Standards
+
+- **Be specific**: "In Work service bulk operations, always use IWorkRepository.BulkUpdateAsync" not "Use async methods"
+- **Be actionable**: "Check WorkRepository.cs:245 for the pattern" not "Follow existing patterns"
+- **Be contextual**: Reference actual files, classes, methods when possible
+- **Be relevant**: Focus on lessons that will help future Claude sessions, not general programming advice
+
+## Examples of Good Lessons
+
+✅ "When adding new bulk operations to Work service, use BulkUpdate domain entity pattern (WorkRepository.cs:245-280) rather than individual update loops. Provides better performance and progress tracking."
+
+✅ "AR service uses legacy .NET Framework 4.8. Cannot use C# 9+ features like records or init-only properties. Check .csproj TargetFramework before suggesting modern syntax."
+
+✅ "Multi-tenant queries MUST include TenantPermaKey filter. Found missing in WorkRepository.GetWorkItems - caused cross-tenant data leak in testing."
+
+❌ "Use async/await for better performance" (too generic)
+❌ "Follow SOLID principles" (not actionable)
+❌ "Write tests" (not specific to this codebase)
+
+## After Writing
+
+Confirm to the user:
+```
+✅ Learning captured as Entry {N} in .sublation-os/memory/{category}-lessons.md
+
+Category: {category}
+This lesson will help future sessions with: {brief description}
+
+You can search for it using tags: {list key tags}
+```
+
+## Notes on Legacy File
+
+The original `learned-lessons.md` file is maintained for backward compatibility. New learnings should go to the categorized files, but you may still read the legacy file if it contains existing entries.

package/.cursor/commands/sublation-os/optimise.md

@@ -0,0 +1,108 @@
+---
+description: Analyze this code for performance issues
+---
+
+# Performance Optimization Analysis
+
+You are a performance optimization specialist for .NET applications. Analyze the selected code or current context for performance issues and provide actionable recommendations.
+
+## Analysis Framework
+
+### 1. Identify Performance Issues
+Scan for these common .NET performance bottlenecks:
+
+**Database & ORM Issues:**
+- N+1 query problems (especially with NHibernate)
+- Missing indexes or inefficient queries
+- Large result sets without pagination
+- SELECT * queries instead of specific columns
+- Unnecessary database round-trips
+- Missing async/await for database operations
+
+**Memory & Resource Issues:**
+- Improper disposal of IDisposable resources
+- Large object allocations
+- String concatenation in loops (use StringBuilder)
+- Boxing/unboxing of value types
+- Memory leaks from event handlers or static references
+- Inefficient LINQ queries causing multiple enumerations
+
+**Concurrency & Threading:**
+- Blocking calls on async code (`.Result`, `.Wait()`)
+- Missing ConfigureAwait(false) in library code
+- Improper use of locks or synchronization
+- Thread pool starvation
+
+**Algorithm & Logic Issues:**
+- Inefficient algorithms (O(n²) when O(n) or O(log n) possible)
+- Unnecessary loops or iterations
+- Redundant computations
+- Missing caching for expensive operations
+
+**API & Network:**
+- Synchronous I/O operations
+- Chatty API calls (multiple calls when one would suffice)
+- Missing response compression
+- Large payloads without pagination
+
+### 2. Prioritize Issues
+Rank findings by:
+- **Impact**: High/Medium/Low performance impact
+- **Effort**: Easy/Medium/Hard to fix
+- **Risk**: Low/Medium/High risk of introducing bugs
+
+### 3. Provide Specific Recommendations
+For each issue found:
+1. **What**: Clearly describe the problem
+2. **Where**: Reference specific file and line numbers (file_path:line_number)
+3. **Why**: Explain the performance impact with estimated improvement if possible
+4. **How**: Provide concrete code examples showing before/after
+5. **Trade-offs**: Mention any downsides or considerations
+
+### 4. Optimization Techniques
+Consider these .NET-specific optimizations:
+- Use `Span<T>` and `Memory<T>` for memory-intensive operations
+- Leverage `ValueTask<T>` for frequently synchronous async methods
+- Apply `readonly struct` for immutable value types
+- Use `ArrayPool<T>` for temporary buffers
+- Implement proper async patterns throughout the call stack
+- Apply lazy initialization for expensive objects
+- Use compiled queries for repeated NHibernate/EF queries
+
+## Output Format
+
+Structure your analysis as:
+
+### 🔴 Critical Issues (Fix Immediately)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### 🟡 Significant Issues (Should Fix Soon)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### 🟢 Minor Improvements (Nice to Have)
+- Issue description with file location
+- Performance impact and fix recommendation
+
+### ✅ Good Practices Found
+- Highlight any exemplary performance patterns
+
+### 📊 Estimated Overall Impact
+- Provide realistic expectations for performance improvements
+
+## Context Awareness
+- Consider the BalancedLabs multi-tenant architecture
+- Account for NHibernate usage patterns
+- Consider IIS hosting implications
+- Be aware of SQL Server query optimization opportunities
+- Reference the CLAUDE.md performance considerations
+
+## Deliverables
+1. Prioritized list of issues with file locations
+2. Code snippets showing recommended changes
+3. Rationale for each recommendation
+4. Estimated performance impact
+5. Implementation difficulty assessment
+
+Begin your analysis now with the selected code or current file context.

package/.cursor/commands/sublation-os/plan-product.md

@@ -0,0 +1,241 @@
+You are helping to plan and document the mission, roadmap and tech stack for the current product.  This will include:
+
+- **Gathering Information**: The user's product vision, user personas, problems and key features
+- **Mission Document**: Take what you've gathered and create a concise mission document
+- **Roadmap**: Create a phased development plan with prioritized features
+- **Tech stack**: Establish the technical stack used for all aspects of this product's codebase
+
+Carefully read and execute the instructions in the following files IN SEQUENCE, following their numbered file names.  Only proceed to the next numbered instruction file once the previous numbered instruction has been executed.
+
+Instructions to follow in sequence:
+
+# PHASE 1: Product Concept
+
+This begins a multi-step process for planning and documenting the mission and roadmap for the current product.
+
+The FIRST STEP is to confirm the product details by following these instructions:
+
+Collect comprehensive product information from the user:
+
+```bash
+# Check if product folder already exists
+if [ -d "agent-os/product" ]; then
+    echo "Product documentation already exists. Review existing files or start fresh?"
+    # List existing product files
+    ls -la agent-os/product/
+fi
+```
+
+Gather from user the following required information:
+- **Product Idea**: Core concept and purpose (required)
+- **Key Features**: Minimum 3 features with descriptions
+- **Target Users**: At least 1 user segment with use cases
+- **Tech stack**: Confirmation or info regarding the product's tech stack choices
+
+If any required information is missing, prompt user:
+```
+Please provide the following to create your product plan:
+1. Main idea for the product
+2. List of key features (minimum 3)
+3. Target users and use cases (minimum 1)
+4. Will this product use your usual tech stack choices or deviate in any way?
+```
+
+
+Then WAIT for me to give you specific instructions on how to use the information you've gathered to create the mission and roadmap.
+
+
+## User Standards & Preferences Compliance
+
+When planning the product's tech stack, mission statement and roadmap, use the user's standards and preferences for context and baseline assumptions, as documented in these files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 2: Create Mission
+
+Now that you've gathered information about this product, use that info to create the mission document in `agent-os/product/mission.md` by following these instructions:
+
+Create `agent-os/product/mission.md` with comprehensive product definition following this structure for its' content:
+
+#### Mission Structure:
+```markdown
+# Product Mission
+
+## Pitch
+[PRODUCT_NAME] is a [PRODUCT_TYPE] that helps [TARGET_USERS] [SOLVE_PROBLEM]
+by providing [KEY_VALUE_PROPOSITION].
+
+## Users
+
+### Primary Customers
+- [CUSTOMER_SEGMENT_1]: [DESCRIPTION]
+- [CUSTOMER_SEGMENT_2]: [DESCRIPTION]
+
+### User Personas
+**[USER_TYPE]** ([AGE_RANGE])
+- **Role:** [JOB_TITLE/CONTEXT]
+- **Context:** [BUSINESS/PERSONAL_CONTEXT]
+- **Pain Points:** [SPECIFIC_PROBLEMS]
+- **Goals:** [DESIRED_OUTCOMES]
+
+## The Problem
+
+### [PROBLEM_TITLE]
+[PROBLEM_DESCRIPTION]. [QUANTIFIABLE_IMPACT].
+
+**Our Solution:** [SOLUTION_APPROACH]
+
+## Differentiators
+
+### [DIFFERENTIATOR_TITLE]
+Unlike [COMPETITOR/ALTERNATIVE], we provide [SPECIFIC_ADVANTAGE].
+This results in [MEASURABLE_BENEFIT].
+
+## Key Features
+
+### Core Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+
+### Collaboration Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+
+### Advanced Features
+- **[FEATURE_NAME]:** [USER_BENEFIT_DESCRIPTION]
+```
+
+#### Important Constraints
+
+- **Focus on user benefits** in feature descriptions, not technical details
+- **Keep it concise** and easy for users to scan and get the more important concepts quickly
+
+
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure the product mission is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 3: Create Roadmap
+
+Now that you've created this product's mission.md, use that to guide your creation of the roadmap in `agent-os/product/roadmap.md` by following these instructions:
+
+Generate `agent-os/product/roadmap.md` with an ordered feature checklist:
+
+Do not include any tasks for initializing a new codebase or bootstrapping a new application. Assume the user is already inside the project's codebase and has a bare-bones application initialized.
+
+#### Creating the Roadmap:
+
+1. **Review the Mission** - Read `agent-os/product/mission.md` to understand the product's goals, target users, and success criteria.
+
+2. **Identify Features** - Based on the mission, determine the list of concrete features needed to achieve the product vision.
+
+3. **Strategic Ordering** - Order features based on:
+   - Technical dependencies (foundational features first)
+   - Most direct path to achieving the mission
+   - Building incrementally from MVP to full product
+
+4. **Create the Roadmap** - Use the structure below as your template. Replace all bracketed placeholders (e.g., `[FEATURE_NAME]`, `[DESCRIPTION]`, `[EFFORT]`) with real content that you create based on the mission.
+
+#### Roadmap Structure:
+```markdown
+# Product Roadmap
+
+1. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+2. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+3. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+4. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+5. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+6. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+7. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+8. [ ] [FEATURE_NAME] — [1-2 SENTENCE DESCRIPTION OF COMPLETE, TESTABLE FEATURE] `[EFFORT]`
+
+> Notes
+> - Order items by technical dependencies and product architecture
+> - Each item should represent an end-to-end (frontend + backend) functional and testable feature
+```
+
+Effort scale:
+- `XS`: 1 day
+- `S`: 2-3 days
+- `M`: 1 week
+- `L`: 2 weeks
+- `XL`: 3+ weeks
+
+#### Important Constraints
+
+- **Make roadmap actionable** - include effort estimates and dependencies
+- **Priorities guided by mission** - When deciding on order, aim for the most direct path to achieving the mission as documented in mission.md
+- **Ensure phases are achievable** - start with MVP, build incrementally
+
+
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure the product roadmap is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md
+
+# PHASE 4: Create Tech Stack
+
+The final part of our product planning process is to document this product's tech stack in `agent-os/product/tech-stack.md`.  Follow these instructions to do so:
+
+Create `agent-os/product/tech-stack.md` with a list of all tech stack choices that cover all aspects of this product's codebase.
+
+### Creating the Tech Stack document
+
+#### Step 1: Note User's Input Regarding Tech Stack
+
+IF the user has provided specific information in the current conversation in regards to tech stack choices, these notes ALWAYS take precidence.  These must be reflected in your final `tech-stack.md` document that you will create.
+
+#### Step 2: Gather User's Default Tech Stack Information
+
+Reconcile and fill in the remaining gaps in the tech stack list by finding, reading and analyzing information regarding the tech stack.  Find this information in the following sources, in this order:
+
+1. If user has provided their default tech stack under "User Standards & Preferences Compliance", READ and analyze this document.
+2. If the current project has any of these files, read them to find information regarding tech stack choices for this codebase:
+  - `claude.md`
+  - `agents.md`
+
+#### Step 3: Create the Tech Stack Document
+
+Create `agent-os/product/tech-stack.md` and populate it with the final list of all technical stack choices, reconciled between the information the user has provided to you and the information found in provided sources.
+
+
+## Display confirmation and next step
+
+Once you've created tech-stack.md, output the following message:
+
+```
+✅ I have documented the product's tech stack at `agent-os/product/tech-stack.md`.
+
+Review it to ensure all of the tech stack details are correct for this product.
+
+You're ready to start planning a feature spec! You can do so by running `shape-spec.md` or `write-spec.md`.
+```
+
+## User Standards & Preferences Compliance
+
+The user may provide information regarding their tech stack, which should take precidence when documenting the product's tech stack.  To fill in any gaps, find the user's usual tech stack information as documented in any of these files:
+
+@agent-os/standards/global/coding-style.md
+@agent-os/standards/global/commenting.md
+@agent-os/standards/global/conventions.md
+@agent-os/standards/global/error-handling.md
+@agent-os/standards/global/tech-stack.md
+@agent-os/standards/global/validation.md

package/.cursor/commands/sublation-os/pr-description.md

@@ -0,0 +1,15 @@
+---
+description: Generate a pull request description
+---
+
+## Title
+{Summarize the PR with a clear, concise title}
+
+## What does this PR do?
+{Describe what this PR accomplishes from a product or user-facing perspective}
+
+## How does it do it?
+{Explain the key code or architectural changes that implement the solution}
+
+## Notes / Validation (optional)
+{Include any testing notes, known issues, or next steps if applicable}

package/.cursor/commands/sublation-os/recall.md

@@ -0,0 +1,114 @@
+---
+description: Search across all memory files to find relevant learnings by keyword or tag
+model: haiku
+---
+
+You are helping the user search for relevant learnings in the Sublation-OS memory system.
+
+## Your Task
+
+Search across all memory files to find learnings that match the user's query. The user may search by:
+- **Keywords** - Any text that might appear in context, lesson, or application sections
+- **Tags** - Specific tags like `#performance`, `#database`, `#api`, etc.
+- **Category** - backend, frontend, testing, architecture, general
+
+## Memory File Locations
+
+Search in these files:
+- `.sublation-os/memory/backend-lessons.md`
+- `.sublation-os/memory/frontend-lessons.md`
+- `.sublation-os/memory/testing-lessons.md`
+- `.sublation-os/memory/architecture-lessons.md`
+- `.sublation-os/memory/general-lessons.md`
+- `.sublation-os/memory/learned-lessons.md` (legacy file for backward compatibility)
+
+## Instructions
+
+1. **Understand the query**: Analyze what the user is looking for
+   - If they mention a specific category, focus on that file first
+   - If they use a hashtag (e.g., `#performance`), search for tags
+   - Otherwise, search for keywords in all text content
+
+2. **Use Grep tool** to search across files:
+   - Use pattern matching for keywords or tags
+   - Search in all memory files unless user specified a category
+   - Use `-A` and `-B` flags to show context around matches
+
+3. **Present results**:
+   - Show entry number, date, and category for each match
+   - Display the relevant sections (Context, Lesson, Application)
+   - If many matches, show top 5 most relevant
+   - Include the file path for reference
+
+4. **Provide navigation**:
+   - Suggest related tags the user might want to search
+   - Mention how many total matches were found
+   - Offer to show more results if there are many
+
+## Example Search Patterns
+
+**Search by tag:**
+```
+User query: "performance"
+→ Use Grep with pattern: `#performance` or `performance` in all memory files
+```
+
+**Search by keyword:**
+```
+User query: "database queries"
+→ Use Grep with pattern: `database.*queries` or just `database` in all memory files
+```
+
+**Search by category:**
+```
+User query: "backend learnings about APIs"
+→ Focus on backend-lessons.md, search for `API` or `api`
+```
+
+## Output Format
+
+Present results like this:
+
+```
+🔍 Found {N} learning(s) matching "{query}":
+
+---
+
+**Entry {N} - {Category}** ({date})
+File: .sublation-os/memory/{category}-lessons.md
+
+### 🧠 Context
+{context text}
+
+### 📘 Lesson
+{lesson text}
+
+### ⚙️ Application
+{application text}
+
+### 🏷️ Tags
+{tags}
+
+---
+
+💡 Related tags you might want to search: {suggested tags}
+```
+
+## If No Results
+
+If no matches are found:
+```
+❌ No learnings found matching "{query}"
+
+Suggestions:
+- Try broader keywords
+- Check spelling and try synonyms
+- Browse categories: backend, frontend, testing, architecture, general
+- Use `/sublation-os:learn` to capture a new learning on this topic
+```
+
+## Additional Features
+
+- If user asks to "show more", display additional results beyond the first 5
+- If user wants to see a specific entry in full, read that file and show the complete entry
+- Suggest creating a new learning if the topic isn't well covered