sublation-os 1.0.0

package/.claude/commands/sublation-os/shape-spec.md

@@ -0,0 +1,52 @@
+# Spec Shaping Process
+
+You are helping me shape and plan the scope for a new feature.  The following process is aimed at documenting our key decisions regarding scope, design and architecture approach.  We will use our findings from this process later when we write the formal spec document (but we are NOT writing the formal spec yet).
+
+This process will follow 3 main phases, each with their own workflow steps:
+
+Process overview (details to follow)
+
+PHASE 1. Initilize spec
+PHASE 2. Research requirements for this spec
+PHASE 3. Inform the user that the spec has been initialized
+
+Follow each of these phases and their individual workflows IN SEQUENCE:
+
+## Multi-Phase Process:
+
+### PHASE 1: Initialize Spec
+
+Use the **spec-shaper** subagent to initialize a new spec.
+
+IF the user has provided a description, provide that to the spec-initializer.
+
+The spec-initializer will provide the path to the dated spec folder (YYYY-MM-DD-spec-name) they've created.
+
+### PHASE 2: Research Requirements
+
+After spec-initializer completes, immediately use the **spec-shaper** subagent:
+
+Provide the spec-shaper with:
+- The spec folder path from spec-initializer
+
+The spec-shaper will give you several separate responses that you MUST show to the user. These include:
+1. Numbered clarifying questions along with a request for visual assets (show these to user, wait for user's response)
+2. Follow-up questions if needed (based on user's answers and provided visuals)
+
+**IMPORTANT**:
+- Display these questions to the user and wait for their response
+- The spec-shaper may ask you to relay follow-up questions that you must present to user
+
+### PHASE 3: Inform the user
+
+After all steps complete, inform the user:
+
+```
+Spec shaping is complete!
+
+✅ Spec folder created: `[spec-path]`
+✅ Requirements gathered
+✅ Visual assets: [Found X files / No files provided]
+
+NEXT STEP 👉 Run `/write-spec` to generate the detailed specification document.
+```

package/.claude/commands/sublation-os/test-plan.md

@@ -0,0 +1,12 @@
+---
+description: Generate a structured test plan from a spec or code sample
+---
+
+## 🎯 Objective
+{Feature or behavior to test}
+
+## 🧪 Test Scenarios
+- {Given/When/Then}
+
+## 🧰 Edge Cases
+- {Corner cases or stress conditions}

package/.claude/commands/sublation-os/write-spec.md

@@ -0,0 +1,22 @@
+# Spec Writing Process
+
+You are creating a comprehensive specification for a new feature.
+
+Use the **spec-writer** subagent to create the specification document for this spec:
+
+Provide the spec-writer with:
+- The spec folder path (find the current one or the most recent in `.sublation-os/specs/*/`)
+- The requirements from `planning/requirements.md`
+- Any visual assets in `planning/visuals/`
+
+The spec-writer will create `spec.md` inside the spec folder.
+
+Once the spec-writer has created `spec.md` output the following to inform the user:
+
+```
+Your spec.md is ready!
+
+✅ Spec document created: `[spec-path]`
+
+NEXT STEP 👉 Run `/create-tasks` to generate your tasks list for this spec.
+```

package/.sublation-os/config.yml

@@ -0,0 +1,13 @@
+version: 2.1.0
+last_compiled: 2025-11-03 20:31:17
+
+# ================================================
+# Compiled with the following settings:
+#
+# To change these settings, run ~/sublation-os/scripts/project-update.sh to re-compile your project with the new settings.
+# ================================================
+profile: default
+claude_code_commands: true
+use_claude_code_subagents: true
+sublation_os_commands: false
+standards_as_claude_code_skills: false

package/.sublation-os/memory/MEMORY_GUIDE.md

@@ -0,0 +1,344 @@
+# Memory System Guide
+
+Welcome to the Sublation-OS memory system! This guide explains how to effectively use the learning and memory features to build up institutional knowledge across AI-assisted development sessions.
+
+---
+
+## 📖 What is the Memory System?
+
+The memory system is a structured approach to capturing and reusing learnings from your development sessions. It helps you:
+
+- **Preserve knowledge** across sessions (no more repeating the same mistakes)
+- **Build institutional memory** about your codebase's patterns and gotchas
+- **Speed up development** by applying proven patterns
+- **Improve quality** by learning from past experiences
+- **Onboard faster** by documenting codebase-specific insights
+
+---
+
+## 🗂️ Memory Structure
+
+The memory system is organized into categorized files:
+
+```
+.sublation-os/memory/
+├── index.md                  # Navigation and search hub
+├── backend-lessons.md        # APIs, databases, services, server-side logic
+├── frontend-lessons.md       # UI components, state management, interactions
+├── testing-lessons.md        # Testing strategies, frameworks, QA
+├── architecture-lessons.md   # System design, patterns, structure
+├── general-lessons.md        # Workflow, tooling, debugging
+└── learned-lessons.md        # Legacy unified file (backward compatibility)
+```
+
+Each category file contains learnings relevant to that domain, making it easier to:
+- Find relevant lessons when working in a specific area
+- Keep the system organized as it scales
+- Allow agents to load only relevant learnings
+
+---
+
+## ✍️ Capturing Learnings
+
+### Using the `/sublation-os:learn` Command
+
+The easiest way to capture a learning is with the `/learn` command:
+
+```
+/sublation-os:learn
+```
+
+The command will:
+1. Analyze your recent conversation context
+2. Determine the appropriate category
+3. Generate a structured entry with:
+   - Context (what happened)
+   - Lesson (the key insight)
+   - Application (how to use this knowledge)
+   - Example (optional code samples)
+   - Tags (for searchability)
+4. Save it to the appropriate category file
+
+### When to Capture Learnings
+
+Capture a learning immediately when you:
+- **Discover a pattern** in the codebase
+- **Fix a bug** that revealed a gotcha
+- **Learn a constraint** (e.g., "Service X uses .NET Framework 4.8")
+- **Find the right approach** after trying alternatives
+- **Correct a mistake** made by AI or human
+- **Identify a performance optimization**
+- **Document a workaround** for a known issue
+
+---
+
+## 🔍 Searching Learnings
+
+### Using the `/sublation-os:recall` Command
+
+Search across all memory files:
+
+```
+/sublation-os:recall [keyword or tag]
+```
+
+Examples:
+- `/sublation-os:recall performance` - Find all performance-related learnings
+- `/sublation-os:recall #database` - Search by tag
+- `/sublation-os:recall API authentication` - Search by keywords
+
+### Manual Search
+
+You can also browse manually:
+1. Open `.sublation-os/memory/index.md` to see all categories
+2. Navigate to a specific category file
+3. Use Ctrl+F to search within the file
+4. Look for 🏷️ Tags sections for topic-based searching
+
+---
+
+## 📝 Entry Structure
+
+Each learning entry follows a consistent structure:
+
+```markdown
+## Entry {N} - {YYYY-MM-DD HH:mm}
+
+### 🧠 Context
+Brief description of the situation or problem (1-2 sentences)
+
+### 📘 Lesson
+The core principle or insight - be specific to this codebase
+
+### ⚙️ Application
+Actionable steps for applying this lesson:
+- Which files/services/patterns this applies to
+- What to check before making similar changes
+- What tools or approaches work best
+
+### 🧩 Example (Optional)
+Code examples showing before/after or do/don't patterns
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+```
+
+---
+
+## 🎯 Writing Quality Learnings
+
+### ✅ Good Learnings Are:
+
+**Specific to Your Codebase:**
+- ✅ "In Work service bulk operations, use IWorkRepository.BulkUpdateAsync (WorkRepository.cs:245)"
+- ❌ "Use async methods for better performance" (too generic)
+
+**Actionable:**
+- ✅ "Check WorkRepository.cs:245 for the pattern before adding new bulk operations"
+- ❌ "Follow existing patterns" (not specific enough)
+
+**Contextual:**
+- ✅ "AR service uses .NET Framework 4.8 - cannot use C# 9+ features like records"
+- ❌ "Use appropriate .NET version" (lacks context)
+
+**Include File References:**
+- ✅ "Multi-tenant queries MUST include TenantPermaKey filter (see WorkRepository.GetWorkItems:127)"
+- ❌ "Remember to filter by tenant" (no reference point)
+
+### ❌ Avoid These:
+
+- Generic programming advice ("Write clean code", "Use SOLID principles")
+- Lessons without file/class/method references
+- Vague recommendations without actionable steps
+- Lessons that don't help future AI sessions understand your codebase
+
+---
+
+## 🤖 How Agents Use Learnings
+
+Sublation-OS agents automatically load and apply learnings:
+
+### Spec Shaper
+- Loads relevant learnings before asking requirement questions
+- Applies past insights about product patterns
+- Avoids asking about issues already documented
+
+### Task List Creator
+- Reads learnings to inform task ordering
+- Applies lessons about dependencies and groupings
+- Considers past mistakes when planning
+
+### Implementer
+- Loads category-specific learnings before coding
+- Follows patterns documented in memory
+- Avoids repeating past mistakes
+- Applies optimization techniques from learnings
+
+### Implementation Verifier
+- Reads learnings about quality standards
+- Checks for common issues documented in memory
+- Applies testing patterns from past learnings
+
+---
+
+## 🏷️ Tagging Best Practices
+
+Tags make learnings discoverable. Use these tag categories:
+
+### Service/Component Tags
+- `#WorkService` `#UserService` `#PaymentProcessor`
+- Specific to your codebase components
+
+### Domain Tags
+- `#performance` `#security` `#authentication` `#validation`
+- General software domains
+
+### Technology Tags
+- `#database` `#api` `#react` `#dotnet` `#sql`
+- Specific technologies used
+
+### Pattern Tags
+- `#async` `#bulkoperations` `#pagination` `#caching`
+- Implementation patterns
+
+### Problem Tags
+- `#debugging` `#memory-leak` `#race-condition`
+- Problem types solved
+
+**Aim for 3-5 tags per entry** for optimal discoverability.
+
+---
+
+## 📊 Maintenance
+
+### Regular Review
+
+Periodically review your learnings:
+- Archive outdated learnings that no longer apply
+- Update learnings when patterns change
+- Add cross-references between related entries
+- Consolidate duplicate or overlapping learnings
+
+### Keep It Lean
+
+Quality over quantity:
+- Remove learnings that became irrelevant
+- Merge similar learnings into comprehensive entries
+- Archive learnings for deprecated features
+
+### Team Collaboration
+
+If working in a team:
+- **Decide on versioning:** Keep memory files in git or gitignore them for personal use
+- **Review together:** Discuss learnings during code reviews
+- **Standardize tags:** Agree on common tag conventions
+- **Share insights:** Review new learnings weekly
+- **Assign ownership:** Designate who curates which categories
+
+---
+
+## 💡 Pro Tips
+
+1. **Capture immediately** - Don't wait, the context will be lost
+2. **Be specific** - Reference exact files, lines, classes, methods
+3. **Include examples** - Before/after code is incredibly valuable
+4. **Tag liberally** - More tags = easier discovery
+5. **Review the index** - Start with `.sublation-os/memory/index.md`
+6. **Use /recall often** - Search before implementing similar features
+7. **Update as you learn** - Keep learnings current and relevant
+8. **Link related learnings** - Cross-reference in the Application section
+
+---
+
+## 🚀 Getting Started
+
+1. **Read the index:** Open `.sublation-os/memory/index.md`
+2. **Browse categories:** Check out the category files to see the structure
+3. **Capture your first learning:** Use `/sublation-os:learn` after fixing your next bug
+4. **Search for relevance:** Use `/sublation-os:recall` when starting new features
+5. **Let agents use it:** Agents will automatically load learnings relevant to their work
+
+---
+
+## 📚 Example Learning
+
+Here's a real-world example of a quality learning:
+
+```markdown
+## Entry 1 - 2025-11-04 14:30
+
+### 🧠 Context
+When implementing pagination for the User list endpoint, the initial implementation loaded all users into memory before applying Skip/Take, causing performance issues with 10K+ users.
+
+### 📘 Lesson
+Always apply pagination at the database query level using IQueryable, not after materialization with ToList(). This ensures only the required page of data is fetched from the database.
+
+### ⚙️ Application
+1. Use IQueryable<T> in repository methods, not IEnumerable<T>
+2. Apply `.Skip()` and `.Take()` before `.ToList()` or `.ToArrayAsync()`
+3. Check UserRepository.GetPagedUsers (line 145) for the correct pattern
+4. Add indexed columns for sorting fields to optimize query performance
+5. Always test pagination with realistic data volumes (1000+ records)
+
+### 🧩 Example
+
+**❌ Wrong - loads all data then paginates in memory:**
+```csharp
+public async Task<List<User>> GetUsers(int page, int size)
+{
+    var allUsers = await _context.Users.ToListAsync(); // ⚠️ Loads everything!
+    return allUsers.Skip(page * size).Take(size).ToList();
+}
+```
+
+**✅ Correct - paginates at database level:**
+```csharp
+public async Task<List<User>> GetUsers(int page, int size)
+{
+    return await _context.Users
+        .OrderBy(u => u.CreatedAt)
+        .Skip(page * size)
+        .Take(size)
+        .ToListAsync();
+}
+```
+
+### 🏷️ Tags
+`#performance` `#database` `#pagination` `#UserService` `#repository-pattern`
+```
+
+---
+
+## 🔗 Related Documentation
+
+- [Setup Guide](../../docs/setup-guide.md) - Initial setup of memory system
+- [Agents & Commands](../../docs/agents-and-commands.md) - How agents use memory
+- [Installation Guide](../../INSTALL.md) - Framework installation
+
+---
+
+## ❓ FAQ
+
+**Q: Should I keep memory files in git?**
+A: It depends! For team projects, keeping them in git shares knowledge. For personal projects, you might prefer to gitignore them.
+
+**Q: How many learnings should I have?**
+A: There's no limit, but aim for quality over quantity. 50-100 well-documented learnings is better than 500 vague ones.
+
+**Q: Can I reorganize categories?**
+A: Yes! The categories are a suggestion. Create custom categories that match your project's needs.
+
+**Q: What if agents aren't using my learnings?**
+A: Ensure learnings are specific and actionable. Generic advice is less useful to AI agents than concrete file references and patterns.
+
+**Q: Can I manually edit memory files?**
+A: Absolutely! Memory files are just markdown. Edit them directly if needed.
+
+**Q: Should I capture every tiny detail?**
+A: No. Focus on non-obvious patterns, gotchas, and codebase-specific insights that would help someone (or some AI) new to the project.
+
+---
+
+Happy learning! 🎓
+
+For questions or feedback, consult the Sublation-OS documentation or your team lead.

package/.sublation-os/memory/architecture-lessons.md

@@ -0,0 +1,41 @@
+# Architecture Lessons
+
+This file contains learnings about system architecture, design patterns, project structure, and cross-cutting concerns.
+
+**Search tips:**
+- Use Ctrl+F to find specific patterns or technologies
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+*Add architecture-specific learned lessons below this line.*

package/.sublation-os/memory/backend-lessons.md

@@ -0,0 +1,41 @@
+# Backend Lessons
+
+This file contains learnings specific to backend development, APIs, databases, services, and server-side logic.
+
+**Search tips:**
+- Use Ctrl+F to find specific patterns or technologies
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+*Add backend-specific learned lessons below this line.*

package/.sublation-os/memory/frontend-lessons.md

@@ -0,0 +1,41 @@
+# Frontend Lessons
+
+This file contains learnings specific to frontend development, UI components, state management, and user interactions.
+
+**Search tips:**
+- Use Ctrl+F to find specific patterns or technologies
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+*Add frontend-specific learned lessons below this line.*

package/.sublation-os/memory/general-lessons.md

@@ -0,0 +1,41 @@
+# General Lessons
+
+This file contains learnings that don't fit into specific categories, including workflow practices, tooling, debugging, and cross-functional insights.
+
+**Search tips:**
+- Use Ctrl+F to find specific patterns or technologies
+- Look for 🏷️ Tags sections to find related lessons
+- Entries are chronological - recent ones are at the bottom
+
+---
+
+## Entry Template
+
+### 🧠 Context
+Describe the situation or problem that led to this learning. What were you trying to accomplish?
+
+### 📘 Lesson
+The key insight or principle learned. What should future Claude sessions remember?
+
+### ⚙️ Application
+How to apply this lesson in practice. Specific steps or guidelines.
+
+### 🧩 Example (Optional)
+Code examples showing the right and wrong way:
+
+**❌ Wrong:**
+```language
+// Anti-pattern code
+```
+
+**✅ Correct:**
+```language
+// Better approach
+```
+
+### 🏷️ Tags
+`#tag1` `#tag2` `#tag3`
+
+---
+
+*Add general learned lessons below this line.*