sublation-os 1.0.2 → 1.1.0

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

@@ -2,11 +2,28 @@
 description: Generate a structured test plan from a spec or code sample
 ---
 
+You are creating a structured test plan for a feature or code sample.
+
+## Test Plan Output Format
+
 ## 🎯 Objective
 {Feature or behavior to test}
 
 ## 🧪 Test Scenarios
-- {Given/When/Then}
+- {Given/When/Then format}
 
 ## 🧰 Edge Cases
-- {Corner cases or stress conditions}
+- {Corner cases or stress conditions}
+
+## Automatic Learning Capture
+
+After creating the test plan, **automatically invoke `auto-learn` skill** if you discovered:
+- Codebase-specific testing patterns that should be followed
+- Edge cases unique to this project's domain
+- Testing anti-patterns found in existing tests
+- Test setup patterns that work well in this codebase
+
+**When to invoke auto-learn:**
+- Found testing convention specific to this codebase → Document it
+- Discovered common edge cases for this domain → Capture them
+- Identified effective test pattern for this stack → Learn it

package/.claude/skills/README.md

@@ -0,0 +1,274 @@
+# Sublation-OS Skills
+
+This directory contains **skills** that are automatically invoked by Claude during development workflows.
+
+## ✅ Correct Skill Structure
+
+Skills in Claude Code must follow this structure:
+
+```
+.claude/skills/
+└── skill-name/          # Directory for each skill
+    └── SKILL.md         # Main skill file (MUST be uppercase!)
+```
+
+### Required SKILL.md Format
+
+Each `SKILL.md` file MUST start with YAML frontmatter:
+
+```yaml
+---
+name: skill-name        # lowercase, hyphens only, max 64 chars
+description: What the skill does and when Claude should use it (max 1024 chars)
+---
+```
+
+**The `description` field is critical** - Claude uses this to decide when to invoke the skill.
+
+---
+
+## Skills vs. Commands
+
+| Type | Invocation | Purpose | Example |
+|------|------------|---------|---------|
+| **Skill** | Claude decides (model-invoked) | Automatic behavior | `auto-learn` skill |
+| **Command** | User types `/command` | Explicit request | `/sublation-os:learn` |
+
+**Key difference:** Skills activate based on context; commands require explicit invocation.
+
+---
+
+## Available Skills
+
+### 🧠 auto-learn
+
+**Location**: `.claude/skills/auto-learn/SKILL.md`
+
+**Purpose**: Automatically capture codebase-specific learnings
+
+**When invoked by Claude**:
+- After completing complex implementations
+- After fixing bugs that reveal patterns
+- After discovering codebase conventions
+- After code reviews that find recurring issues
+
+**Integration points**:
+- `implementer-v2` agent - Invokes after implementation reflection
+- `/sublation-os:review-v2` - Invokes when finding recurring patterns
+- `/sublation-os:investigate` - Invokes after root cause analysis
+- And 7 other commands/agents
+
+**Output**: Creates entries in `.sublation-os/memory/{category}-lessons.md`
+
+**How to invoke**: Don't! Claude invokes it automatically when appropriate.
+
+**Manual alternative**: Use `/sublation-os:learn` for explicit control
+
+---
+
+## How Skills Work
+
+### Discovery
+
+Skills are automatically discovered from:
+1. **Project skills**: `.claude/skills/` (shared with team via git)
+2. **Personal skills**: `~/.claude/skills/` (available across all your projects)
+3. **Plugin skills**: Installed via plugin marketplace
+
+### Invocation
+
+When you make a request, Claude:
+1. Reads skill descriptions
+2. Determines which skill (if any) is relevant
+3. Invokes the skill automatically
+4. Executes the skill's instructions
+
+You'll see: `<command-message>The "skill-name" skill is loading</command-message>`
+
+### Progressive Disclosure
+
+Claude only reads SKILL.md when the skill is invoked, managing context efficiently.
+
+---
+
+## Creating New Skills
+
+### Step 1: Create Directory Structure
+
+```bash
+mkdir -p .claude/skills/my-skill
+```
+
+### Step 2: Create SKILL.md
+
+```bash
+cat > .claude/skills/my-skill/SKILL.md << 'EOF'
+---
+name: my-skill
+description: Clear explanation of what this skill does and when to use it
+---
+
+You are [role description].
+
+## Instructions
+
+[Detailed instructions for the skill]
+
+## Steps
+
+[Step-by-step workflow]
+EOF
+```
+
+### Step 3: Write a Good Description
+
+The description field determines **when Claude invokes the skill**. Make it:
+- **Specific**: What exact scenarios trigger this?
+- **Clear**: What capability does this provide?
+- **Actionable**: When should Claude use this vs. other skills?
+- **Concise**: Max 1024 characters
+
+**Good description:**
+```yaml
+description: Automatically capture codebase-specific learnings after implementations, bug fixes, or code reviews. Invoked when discovering non-obvious patterns, fixing mistakes, or finding recurring issues (3+ occurrences). Saves structured entries to .sublation-os/memory/.
+```
+
+**Bad description:**
+```yaml
+description: Helps with learning stuff
+```
+
+### Step 4: Test the Skill
+
+Work normally and see if Claude invokes your skill appropriately. Check that:
+- It triggers in the right scenarios
+- It doesn't trigger too often (be selective)
+- The output is useful
+
+---
+
+## Skill Design Principles
+
+### ✅ DO:
+
+- Design for automatic, silent invocation
+- Keep output minimal (users didn't explicitly ask)
+- Be selective about when to invoke
+- Follow consistent formats with related commands
+- Document integration points clearly
+- Use clear, specific descriptions
+
+### ❌ DON'T:
+
+- Require user interaction or confirmation
+- Produce verbose output
+- Invoke for trivial or routine work
+- Duplicate work that commands already do
+- Create side effects users wouldn't expect
+- Use vague descriptions
+
+---
+
+## Comparison: Skills vs. Slash Commands
+
+### When to Create a Skill
+
+Use a skill when:
+- Claude should decide when to use it (automatic)
+- It enhances ongoing work without explicit invocation
+- The trigger conditions are clear and detectable
+- It provides capabilities Claude needs autonomously
+
+**Examples**: auto-learn, auto-test, auto-format
+
+### When to Create a Slash Command
+
+Use a slash command when:
+- Users should explicitly control when it runs
+- It's a distinct workflow users initiate
+- The user needs to provide specific inputs
+- It's not always relevant to ongoing work
+
+**Examples**: /learn (manual control), /review (explicit request), /investigate (user-triggered)
+
+---
+
+## Future Skill Ideas
+
+Potential skills to implement:
+
+- **auto-test** - Automatically run relevant tests after code changes
+- **auto-document** - Generate inline documentation for complex functions
+- **auto-refactor-suggest** - Suggest refactoring when complexity is high
+- **auto-security-check** - Scan for common security issues
+- **auto-performance-profile** - Identify performance bottlenecks
+
+---
+
+## File Structure Reference
+
+```
+.claude/skills/
+├── README.md              # This file
+└── auto-learn/            # Skill directory
+    └── SKILL.md           # Main skill file (uppercase!)
+```
+
+**Additional optional files per skill:**
+```
+skill-name/
+├── SKILL.md               # Required
+├── reference.md           # Optional reference docs
+├── scripts/               # Optional scripts
+└── templates/             # Optional templates
+```
+
+---
+
+## Related Documentation
+
+- **Commands**: `.claude/commands/sublation-os/` - User-invoked slash commands
+- **Agents**: `.claude/agents/sublation-os/` - Specialized implementation agents
+- **Memory**: `.sublation-os/memory/` - Where auto-learn saves learnings
+- **Skills Guide**: `docs/skills-guide.md` - Comprehensive user guide
+- **Integration Map**: `docs/auto-learn-integration.md` - All integration points
+
+---
+
+## Troubleshooting
+
+### Skill Not Appearing
+
+**Problem**: Skill not being invoked by Claude
+
+**Check**:
+1. Is SKILL.md uppercase? (`SKILL.md` not `skill.md`)
+2. Is it in the right location? (`.claude/skills/skill-name/SKILL.md`)
+3. Does it have valid YAML frontmatter with `name` and `description`?
+4. Is the description clear about when to invoke?
+
+### Skill Invoked Too Often
+
+**Problem**: Skill triggers too frequently
+
+**Solution**: Make the description more specific about trigger conditions
+
+### Skill Never Invoked
+
+**Problem**: Claude never uses the skill
+
+**Solution**: Broaden the description to include more scenarios, or make trigger conditions clearer
+
+---
+
+## Official Documentation
+
+For more information, see:
+- [Claude Code Skills Documentation](https://code.claude.com/docs/en/skills)
+- [GitHub: Anthropic Skills Repository](https://github.com/anthropics/skills)
+
+---
+
+**Current Skills**: 1 (auto-learn)
+
+**Status**: ✅ Properly configured and operational

package/.claude/skills/auto-learn/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: auto-learn
+description: Automatically capture codebase-specific learnings after implementations, bug fixes, code reviews, or investigations. Invoked when discovering non-obvious patterns, fixing mistakes, finding recurring issues (3+ occurrences), or uncovering architectural insights. Saves structured entries to .sublation-os/memory/ for future sessions.
+---
+
+You are automatically capturing a learning moment from recent work to help future Claude sessions work more effectively on this codebase.
+
+## When This Skill is Invoked
+
+This skill should be proactively invoked by Claude (not the user) after:
+- ✅ Completing a complex implementation with non-obvious solutions
+- ✅ Fixing a bug that revealed a pattern or gotcha
+- ✅ Discovering codebase-specific conventions or patterns
+- ✅ Making a mistake and correcting it
+- ✅ Finding performance optimizations specific to this codebase
+- ✅ Completing code review that identified recurring issues
+- ✅ Investigating errors that revealed architectural insights
+- ✅ Using a tool or approach that worked particularly well (or poorly)
+
+**Do NOT invoke for:**
+- Trivial changes or routine work
+- General programming knowledge (not codebase-specific)
+- Changes already documented in standards
+- Learning that doesn't provide future value
+
+---
+
+## Your Task
+
+Analyze the recent work in this session and automatically generate a structured learning entry.
+
+### Step 0: Should This Be Captured?
+
+Before proceeding, verify this learning is worth capturing:
+
+**Ask yourself:**
+1. Is this specific to THIS codebase (not general programming advice)?
+2. Would future Claude sessions benefit from knowing this?
+3. Is this a mistake/pattern that could be repeated?
+4. Does this reveal something non-obvious about the architecture?
+
+If you answer "no" to all questions, **STOP** - don't create a learning entry.
+
+If YES to any question, proceed to capture the learning.
+
+---
+
+## Step 1: Analyze Recent Context
+
+Examine the recent conversation to identify:
+
+**What happened?**
+- What task was being performed?
+- What approach was initially tried?
+- What correction or insight occurred?
+- What was learned that wasn't obvious?
+
+**Why does this matter?**
+- How does this affect future work?
+- What mistake does this prevent?
+- What pattern should be followed?
+
+**Evidence:**
+- What files or code demonstrate this?
+- Where can future sessions see the pattern?
+
+---
+
+## Step 2: Determine Category
+
+Automatically classify this learning into one category:
+
+- **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
+
+Target file: `.sublation-os/memory/{category}-lessons.md`
+
+---
+
+## Step 3: Read Existing File
+
+Read the target category file to:
+1. Determine the next entry number (check for "## Entry {N}")
+2. Ensure consistent formatting
+3. Verify this isn't a duplicate learning
+
+If file doesn't exist, start with Entry 1 and create the file with the header template (see Step 5).
+
+---
+
+## Step 4: Generate Learning Entry
+
+Create the entry using 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. Include code if relevant.}
+
+### 🏷️ Tags
+{Comma-separated tags for searchability: e.g., "Work service, bulk operations, async patterns, testing"}
+
+---
+
+```
+
+**Quality Standards:**
+- ✅ **Be specific**: Reference actual files, classes, methods
+- ✅ **Be actionable**: Provide concrete guidance
+- ✅ **Be contextual**: Tie to this codebase, not general advice
+- ✅ **Be valuable**: Focus on non-obvious insights
+
+**Examples of GOOD learnings:**
+- "When adding bulk operations to Work service, use BulkUpdate domain entity pattern (WorkRepository.cs:245-280) rather than individual update loops"
+- "AR service uses .NET Framework 4.8 - cannot use C# 9+ features like records"
+- "Multi-tenant queries MUST include TenantPermaKey filter - caused cross-tenant leak in WorkRepository.GetWorkItems"
+
+**Examples of BAD learnings:**
+- "Use async/await for better performance" (too generic)
+- "Follow SOLID principles" (not actionable)
+- "Write tests" (not specific to this codebase)
+
+---
+
+## Step 5: Append to Memory File
+
+### If file exists:
+Append the new entry to the end of `.sublation-os/memory/{category}-lessons.md`
+
+### If file doesn't exist (new category):
+Create the file with this header first:
+
+```markdown
+# {Category} Lessons
+
+This file contains durable learnings from Claude Code sessions to help future sessions work more effectively on this codebase.
+
+**Category**: {Category}
+
+**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
+
+---
+
+```
+
+Then append the new entry.
+
+---
+
+## Step 6: Silently Update Index (Optional)
+
+If this is a significant learning or introduces new tags:
+
+1. Read `.sublation-os/memory/index.md`
+2. Check if the new tags exist in the tag index
+3. If not, add them to the appropriate section
+4. Update entry count statistics
+
+**Note:** Only update index for significant learnings. Don't update for every entry.
+
+---
+
+## Step 7: Silent Confirmation
+
+After capturing the learning, OUTPUT a brief confirmation to the conversation:
+
+```
+💡 Captured learning: {brief one-line description}
+   → Saved as Entry {N} in {category}-lessons.md
+   → Tags: {key tags}
+```
+
+**Keep it minimal** - this is automatic, not a user-requested action.
+
+---
+
+## Integration Points
+
+This skill works alongside:
+
+- **`/sublation-os:learn`** - User-invoked version for explicit learning capture
+- **`implementer-v2`** - Should invoke this after implementation reflection
+- **`/sublation-os:investigate`** - Should invoke this after root cause analysis
+- **`/sublation-os:review-v2`** - Should invoke this after finding recurring patterns
+- **Any agent** - Can invoke when discovering codebase-specific insights
+
+---
+
+## Decision Tree: Should I Invoke Auto-Learn?
+
+```
+Did I just...
+├─ Fix a bug that revealed a codebase gotcha? → YES, invoke
+├─ Implement something using a non-obvious pattern? → YES, invoke
+├─ Correct an initial mistake with a better approach? → YES, invoke
+├─ Discover a codebase-specific convention? → YES, invoke
+├─ Find an architecture insight while exploring? → YES, invoke
+├─ Use a tool/approach that worked particularly well? → YES, invoke
+├─ Complete a routine task following known patterns? → NO, skip
+├─ Apply general programming knowledge? → NO, skip
+└─ Make a trivial change? → NO, skip
+```
+
+---
+
+## Notes
+
+- **Be selective**: Don't capture every small thing, only valuable insights
+- **Be specific**: Always reference concrete files and line numbers when possible
+- **Be quiet**: Keep confirmation minimal since this is automatic
+- **Be consistent**: Use the exact format from /learn command
+- **Be valuable**: Focus on things that will help future sessions
+
+This skill builds institutional knowledge automatically, making Claude more effective over time.

package/.cursor/commands/sublation-os/address-comments.md

@@ -0,0 +1,74 @@
+---
+description: Fetch PR comments and address them systematically
+model: sonnet
+---
+
+# Address PR Comments
+
+You are tasked with fetching all comments from the current pull request and addressing them systematically.
+
+## Instructions
+
+1. **Fetch PR Information**
+   - Use `gh pr view --json number` to get the current PR number
+   - If no PR exists for the current branch, inform the user and stop
+
+2. **Fetch PR Comments**
+   - Use `gh api repos/:owner/:repo/pulls/{PR_NUMBER}/comments` to get review comments
+   - Use `gh pr view --json comments` to get general PR comments
+   - Parse and organize comments by file and line number where applicable
+
+3. **Analyze Comments**
+   - Read each comment carefully
+   - Categorize comments by type:
+     - Code changes required
+     - Questions to clarify
+     - Suggestions for improvement
+     - Informational/acknowledgments
+   - Prioritize actionable comments
+
+4. **Create Action Plan**
+   - Use the TodoWrite tool to create a structured task list with:
+     - Each actionable comment as a separate task
+     - File path and line number references where applicable
+     - Brief description of what needs to be addressed
+   - Group related comments together
+
+5. **Address Each Comment**
+   - Work through the todo list systematically
+   - For each comment:
+     - Read the relevant code using serena tools (find_symbol, get_symbols_overview)
+     - Make the requested changes or improvements
+     - If clarification is needed, note it for the user
+     - Mark the todo as completed once addressed
+
+6. **Verify Changes**
+   - After addressing all comments, run relevant tests
+   - Ensure code builds successfully
+   - Review the changes to confirm all comments have been addressed
+
+7. **Summary Report**
+   - Provide a summary of:
+     - Total comments found
+     - Comments addressed
+     - Comments requiring user input/clarification
+     - Any comments skipped and why
+   - Suggest next steps (e.g., respond to reviewers, push changes)
+
+## Guidelines
+
+- Be thorough but efficient - use serena's symbolic tools to read only necessary code
+- If a comment is unclear, ask the user for clarification before making changes
+- Respect the reviewer's intent - if unsure, err on the side of asking
+- Follow the project's coding standards and patterns (check CLAUDE.md context)
+- Test your changes after addressing comments when possible
+- For .NET code, ensure you follow Clean Architecture and DDD principles
+
+## Output Format
+
+Provide clear feedback after each step:
+- "Found X comments on PR #Y"
+- "Created todo list with Z actionable items"
+- "Addressing comment: {comment summary}"
+- "Completed: {what was changed}"
+- Final summary with all changes made

package/.cursor/commands/sublation-os/commit-message.md

@@ -0,0 +1,84 @@
+---
+description: Generate a commit message based on code changes
+model: haiku
+---
+
+# Generate Commit Message
+
+You are tasked with analyzing the current code changes and generating an appropriate commit message following the project's conventions.
+
+## Instructions
+
+1. **Analyze Changes**
+   - Run `git status` to see modified/added/deleted files
+   - Run `git diff --staged` to see staged changes (if any)
+   - Run `git diff` to see unstaged changes
+   - Identify the scope and nature of changes
+
+2. **Review Recent Commits**
+   - Run `git log --oneline -10` to see recent commit message patterns
+   - Note the project's commit message format (appears to use conventional commits)
+
+3. **Categorize Changes**
+   - Determine the change type:
+     - `feat` - New feature
+     - `fix` - Bug fix
+     - `refactor` - Code refactoring
+     - `test` - Adding or updating tests
+     - `docs` - Documentation changes
+     - `chore` - Build, dependencies, or tooling
+     - `perf` - Performance improvements
+     - `style` - Code style/formatting
+   - Identify the affected service/pillar (e.g., work, contacts, accounting)
+
+4. **Generate Commit Message**
+   Format: `{type}({scope}): {description}`
+
+   Examples from this repo:
+   - `feat(work): Add bulk reset status endpoint`
+   - `fix(contacts): Resolve email validation issue`
+   - `refactor(accounting): Simplify invoice calculation logic`
+
+   Guidelines:
+   - Keep description concise (50-72 chars for first line)
+   - Use imperative mood ("Add" not "Added" or "Adds")
+   - Focus on WHAT and WHY, not HOW
+   - Be specific but brief
+   - No period at the end of the subject line
+   - If changes span multiple files/areas, focus on the primary purpose
+
+5. **Add Body (Optional)**
+   - If the change is complex, add a blank line and detailed body
+   - Explain WHY the change was made
+   - Reference any tickets/issues: `Refs: OTT-852`
+   - Break lines at 72 characters
+
+6. **Output Format**
+   Provide the commit message in a code block that can be easily copied:
+
+   ```
+   {type}({scope}): {description}
+
+   {optional body}
+
+   {optional footer with refs/breaking changes}
+   ```
+
+## Example Output
+
+```
+feat(work): Add GetBulkResetStatus endpoint with workTemplatePermaKey support
+
+Enable querying bulk reset status by either bulkUpdatePermaKey or
+workTemplatePermaKey. Updated validation to ensure exactly one key
+is provided. Added comprehensive test coverage.
+
+Refs: OTT-852
+```
+
+## Notes
+
+- If no changes are staged, analyze unstaged changes
+- If changes are trivial (whitespace, comments), suggest a simpler message
+- If changes span multiple concerns, recommend splitting into separate commits
+- Follow the existing patterns in the codebase (check recent git log)