sublation-os 1.0.2 → 1.1.0

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

@@ -0,0 +1,395 @@
+You are helping me shape and plan the scope for a new feature.  The following MULTI-PHASE process is aimed at documenting our key decisions regarding scope, design and architecture approach.
+
+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: Initialize Spec
+
+The FIRST STEP is to initialize the spec by following these instructions:
+
+# Spec Initialization
+
+## Core Responsibilities
+
+1. **Get the description of the feature:** Receive it from the user or check the product roadmap
+2. **Initialize Spec Structure**: Create the spec folder with date prefix
+3. **Save Raw Idea**: Document the user's exact description without modification
+4. **Create Create Implementation & Verification Folders**: Setup folder structure for tracking implementation of this spec.
+5. **Prepare for Requirements**: Set up structure for next phase
+
+## Workflow
+
+### Step 1: Get the description of the feature
+
+IF you were given a description of the feature, then use that to initiate a new spec.
+
+OTHERWISE follow these steps to get the description:
+
+1. Check `@agent-os/product/roadmap.md` to find the next feature in the roadmap.
+2. OUTPUT the following to user and WAIT for user's response:
+
+```
+Which feature would you like to initiate a new spec for?
+
+- The roadmap shows [feature description] is next. Go with that?
+- Or provide a description of a feature you'd like to initiate a spec for.
+```
+
+**If you have not yet received a description from the user, WAIT until user responds.**
+
+### Step 2: Initialize Spec Structure
+
+Determine a kebab-case spec name from the user's description, then create the spec folder:
+
+```bash
+# Get today's date in YYYY-MM-DD format
+TODAY=$(date +%Y-%m-%d)
+
+# Determine kebab-case spec name from user's description
+SPEC_NAME="[kebab-case-name]"
+
+# Create dated folder name
+DATED_SPEC_NAME="${TODAY}-${SPEC_NAME}"
+
+# Store this path for output
+SPEC_PATH="agent-os/specs/$DATED_SPEC_NAME"
+
+# Create folder structure following architecture
+mkdir -p $SPEC_PATH/planning
+mkdir -p $SPEC_PATH/planning/visuals
+
+echo "Created spec folder: $SPEC_PATH"
+```
+
+### Step 3: Create Implementation Folder
+
+Create 2 folders:
+- `$SPEC_PATH/implementation/`
+
+Leave this folder empty, for now. Later, this folder will be populated with reports documented by implementation agents.
+
+### Step 4: Output Confirmation
+
+Return or output the following:
+
+```
+Spec folder initialized: `[spec-path]`
+
+Structure created:
+- planning/ - For requirements and specifications
+- planning/visuals/ - For mockups and screenshots
+- implementation/ - For implementation documentation
+
+Ready for requirements research phase.
+```
+
+## Important Constraints
+
+- Always use dated folder names (YYYY-MM-DD-spec-name)
+- Pass the exact spec path back to the orchestrator
+- Follow folder structure exactly
+- Implementation folder should be empty, for now
+
+# PHASE 2: Shape Spec
+
+Now that you've initialized the folder for this new spec, proceed with the research phase.
+
+Follow these instructions for researching this spec's requirements:
+
+# Spec Research
+
+## Core Responsibilities
+
+1. **Read Initial Idea**: Load the raw idea from initialization.md
+2. **Analyze Product Context**: Understand product mission, roadmap, and how this feature fits
+3. **Ask Clarifying Questions**: Generate targeted questions WITH visual asset request AND reusability check
+4. **Process Answers**: Analyze responses and any provided visuals
+5. **Ask Follow-ups**: Based on answers and visual analysis if needed
+6. **Save Requirements**: Document the requirements you've gathered to a single file named: `[spec-path]/planning/requirements.md`
+
+## Workflow
+
+### Step 1: Read Initial Idea
+
+Read the raw idea from `[spec-path]/planning/initialization.md` to understand what the user wants to build.
+
+### Step 2: Analyze Product Context
+
+Before generating questions, understand the broader product context:
+
+1. **Read Product Mission**: Load `agent-os/product/mission.md` to understand:
+   - The product's overall mission and purpose
+   - Target users and their primary use cases
+   - Core problems the product aims to solve
+   - How users are expected to benefit
+
+2. **Read Product Roadmap**: Load `agent-os/product/roadmap.md` to understand:
+   - Features and capabilities already completed
+   - The current state of the product
+   - Where this new feature fits in the broader roadmap
+   - Related features that might inform or constrain this work
+
+3. **Read Product Tech Stack**: Load `agent-os/product/tech-stack.md` to understand:
+   - Technologies and frameworks in use
+   - Technical constraints and capabilities
+   - Libraries and tools available
+
+This context will help you:
+- Ask more relevant and contextual questions
+- Identify existing features that might be reused or referenced
+- Ensure the feature aligns with product goals
+- Understand user needs and expectations
+
+### Step 3: Generate First Round of Questions WITH Visual Request AND Reusability Check
+
+Based on the initial idea, generate 4-8 targeted, NUMBERED questions that explore requirements while suggesting reasonable defaults.
+
+**CRITICAL: Always include the visual asset request AND reusability question at the END of your questions.**
+
+**Question generation guidelines:**
+- Start each question with a number
+- Propose sensible assumptions based on best practices
+- Frame questions as "I'm assuming X, is that correct?"
+- Make it easy for users to confirm or provide alternatives
+- Include specific suggestions they can say yes/no to
+- Always end with an open question about exclusions
+
+**Required output format:**
+```
+Based on your idea for [spec name], I have some clarifying questions:
+
+1. I assume [specific assumption]. Is that correct, or [alternative]?
+2. I'm thinking [specific approach]. Should we [alternative]?
+3. [Continue with numbered questions...]
+[Last numbered question about exclusions]
+
+**Existing Code Reuse:**
+Are there existing features in your codebase with similar patterns we should reference? For example:
+- Similar interface elements or UI components to re-use
+- Comparable page layouts or navigation patterns
+- Related backend logic or service objects
+- Existing models or controllers with similar functionality
+
+Please provide file/folder paths or names of these features if they exist.
+
+**Visual Assets Request:**
+Do you have any design mockups, wireframes, or screenshots that could help guide the development?
+
+If yes, please place them in: `[spec-path]/planning/visuals/`
+
+Use descriptive file names like:
+- homepage-mockup.png
+- dashboard-wireframe.jpg
+- lofi-form-layout.png
+- mobile-view.png
+- existing-ui-screenshot.png
+
+Please answer the questions above and let me know if you've added any visual files or can point to similar existing features.
+```
+
+**OUTPUT these questions to the orchestrator and STOP - wait for user response.**
+
+### Step 4: Process Answers and MANDATORY Visual Check
+
+After receiving user's answers from the orchestrator:
+
+1. Store the user's answers for later documentation
+
+2. **MANDATORY: Check for visual assets regardless of user's response:**
+
+**CRITICAL**: You MUST run the following bash command even if the user says "no visuals" or doesn't mention visuals (Users often add files without mentioning them):
+
+```bash
+# List all files in visuals folder - THIS IS MANDATORY
+ls -la [spec-path]/planning/visuals/ 2>/dev/null | grep -E '\.(png|jpg|jpeg|gif|svg|pdf)$' || echo "No visual files found"
+```
+
+3. IF visual files are found (bash command returns filenames):
+   - Use Read tool to analyze EACH visual file found
+   - Note key design elements, patterns, and user flows
+   - Document observations for each file
+   - Check filenames for low-fidelity indicators (lofi, lo-fi, wireframe, sketch, rough, etc.)
+
+4. IF user provided paths or names of similar features:
+   - Make note of these paths/names for spec-writer to reference
+   - DO NOT explore them yourself (to save time), but DO document their names for future reference by the spec-writer.
+
+### Step 5: Generate Follow-up Questions (if needed)
+
+Determine if follow-up questions are needed based on:
+
+**Visual-triggered follow-ups:**
+- If visuals were found but user didn't mention them: "I found [filename(s)] in the visuals folder. Let me analyze these for the specification."
+- If filenames contain "lofi", "lo-fi", "wireframe", "sketch", or "rough": "I notice you've provided [filename(s)] which appear to be wireframes/low-fidelity mockups. Should we treat these as layout and structure guides rather than exact design specifications, using our application's existing styling instead?"
+- If visuals show features not discussed in answers
+- If there are discrepancies between answers and visuals
+
+**Reusability follow-ups:**
+   - If user didn't provide similar features but the spec seems common: "This seems like it might share patterns with existing features. Could you point me to any similar forms/pages/logic in your app?"
+- If provided paths seem incomplete you can ask something like: "You mentioned [feature]. Are there any service objects or backend logic we should also reference?"
+
+**User's Answers-triggered follow-ups:**
+- Vague requirements need clarification
+- Missing technical details
+- Unclear scope boundaries
+
+**If follow-ups needed, OUTPUT to orchestrator:**
+```
+Based on your answers [and the visual files I found], I have a few follow-up questions:
+
+1. [Specific follow-up question]
+2. [Another follow-up if needed]
+
+Please provide these additional details.
+```
+
+**Then STOP and wait for responses.**
+
+### Step 6: Save Complete Requirements
+
+After all questions are answered, record ALL gathered information to ONE FILE at this location with this name: `[spec-path]/planning/requirements.md`
+
+Use the following structure and do not deviate from this structure when writing your gathered information to `requirements.md`.  Include ONLY the items specified in the following structure:
+
+```markdown
+# Spec Requirements: [Spec Name]
+
+## Initial Description
+[User's original spec description from initialization.md]
+
+## Requirements Discussion
+
+### First Round Questions
+
+**Q1:** [First question asked]
+**Answer:** [User's answer]
+
+**Q2:** [Second question asked]
+**Answer:** [User's answer]
+
+[Continue for all questions]
+
+### Existing Code to Reference
+[Based on user's response about similar features]
+
+**Similar Features Identified:**
+- Feature: [Name] - Path: `[path provided by user]`
+- Components to potentially reuse: [user's description]
+- Backend logic to reference: [user's description]
+
+[If user provided no similar features]
+No similar existing features identified for reference.
+
+### Follow-up Questions
+[If any were asked]
+
+**Follow-up 1:** [Question]
+**Answer:** [User's answer]
+
+## Visual Assets
+
+### Files Provided:
+[Based on actual bash check, not user statement]
+- `filename.png`: [Description of what it shows from your analysis]
+- `filename2.jpg`: [Key elements observed from your analysis]
+
+### Visual Insights:
+- [Design patterns identified]
+- [User flow implications]
+- [UI components shown]
+- [Fidelity level: high-fidelity mockup / low-fidelity wireframe]
+
+[If bash check found no files]
+No visual assets provided.
+
+## Requirements Summary
+
+### Functional Requirements
+- [Core functionality based on answers]
+- [User actions enabled]
+- [Data to be managed]
+
+### Reusability Opportunities
+- [Components that might exist already based on user's input]
+- [Backend patterns to investigate]
+- [Similar features to model after]
+
+### Scope Boundaries
+**In Scope:**
+- [What will be built]
+
+**Out of Scope:**
+- [What won't be built]
+- [Future enhancements mentioned]
+
+### Technical Considerations
+- [Integration points mentioned]
+- [Existing system constraints]
+- [Technology preferences stated]
+- [Similar code patterns to follow]
+```
+
+### Step 7: Output Completion
+
+Return to orchestrator:
+
+```
+Requirements research complete!
+
+✅ Processed [X] clarifying questions
+✅ Visual check performed: [Found and analyzed Y files / No files found]
+✅ Reusability opportunities: [Identified Z similar features / None identified]
+✅ Requirements documented comprehensively
+
+Requirements saved to: `[spec-path]/planning/requirements.md`
+
+Ready for specification creation.
+```
+
+## Important Constraints
+
+- **MANDATORY**: Always run bash command to check visuals folder after receiving user answers
+- DO NOT write technical specifications for development. Just record your findings from information gathering to this single file: `[spec-path]/planning/requirements.md`.
+- Visual check is based on actual file(s) found via bash, NOT user statements
+- Check filenames for low-fidelity indicators and clarify design intent if found
+- Ask about existing similar features to promote code reuse
+- Keep follow-ups minimal (1-3 questions max)
+- Save user's exact answers, not interpretations
+- Document all visual findings including fidelity level
+- Document paths to similar features for spec-writer to reference
+- OUTPUT questions and STOP to wait for orchestrator to relay responses
+
+
+## Display confirmation and next step
+
+Once you've completed your research and documented it, output the following message:
+
+```
+✅ I have documented this spec's research and requirements in `agent-os/specs/[this-spec]/planning`.
+
+Next step: Run the command, `1-create-spec.md`.
+```
+
+After all steps complete, inform the user:
+
+```
+Spec initialized successfully!
+
+✅ Spec folder created: `[spec-path]`
+✅ Requirements gathered
+✅ Visual assets: [Found X files / No files provided]
+
+👉 Run `/write-spec` to create the spec.md document.
+```
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure that your research questions and insights are 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

package/.cursor/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/.cursor/commands/sublation-os/write-spec.md

@@ -0,0 +1,134 @@
+Now that we've initiated and planned the details for a new spec, we will now proceed with drafting the specification document, following these instructions:
+
+# Spec Writing
+
+## Core Responsibilities
+
+1. **Analyze Requirements**: Load and analyze requirements and visual assets thoroughly
+2. **Search for Reusable Code**: Find reusable components and patterns in existing codebase
+3. **Create Specification**: Write comprehensive specification document
+
+## Workflow
+
+### Step 1: Analyze Requirements and Context
+
+Read and understand all inputs and THINK HARD:
+```bash
+# Read the requirements document
+cat sublation-os/specs/[current-spec]/planning/requirements.md
+
+# Check for visual assets
+ls -la sublation-os/specs/[current-spec]/planning/visuals/ 2>/dev/null | grep -v "^total" | grep -v "^d"
+```
+
+Parse and analyze:
+- User's feature description and goals
+- Requirements gathered by spec-shaper
+- Visual mockups or screenshots (if present)
+- Any constraints or out-of-scope items mentioned
+
+### Step 2: Search for Reusable Code
+
+Before creating specifications, search the codebase for existing patterns and components that can be reused.
+
+Based on the feature requirements, identify relevant keywords and search for:
+- Similar features or functionality
+- Existing UI components that match your needs
+- Models, services, or controllers with related logic
+- API patterns that could be extended
+- Database structures that could be reused
+
+Use appropriate search tools and commands for the project's technology stack to find:
+- Components that can be reused or extended
+- Patterns to follow from similar features
+- Naming conventions used in the codebase
+- Architecture patterns already established
+
+Document your findings for use in the specification.
+
+### Step 3: Create Core Specification
+
+Write the main specification to `sublation-os/specs/[current-spec]/spec.md`.
+
+DO NOT write actual code in the spec.md document. Just describe the requirements clearly and concisely.
+
+Keep it short and include only essential information for each section.
+
+Follow this structure exactly when creating the content of `spec.md`:
+
+```markdown
+# Specification: [Feature Name]
+
+## Goal
+[1-2 sentences describing the core objective]
+
+## User Stories
+- As a [user type], I want to [action] so that [benefit]
+- [repeat for up to 2 max additional user stories]
+
+## Specific Requirements
+
+**Specific requirement name**
+- [Up to 8 CONCISE sub-bullet points to clarify specific sub-requirements, design or architectual decisions that go into this requirement, or the technical approach to take when implementing this requirement]
+
+[repeat for up to a max of 10 specific requirements]
+
+## Visual Design
+[If mockups provided]
+
+**`planning/visuals/[filename]`**
+- [up to 8 CONCISE bullets describing specific UI elements found in this visual to address when building]
+
+[repeat for each file in the `planning/visuals` folder]
+
+## Existing Code to Leverage
+
+**Code, component, or existing logic found**
+- [up to 5 bullets that describe what this existing code does and how it should be re-used or replicated when building this spec]
+
+[repeat for up to 5 existing code areas]
+
+## Out of Scope
+- [up to 10 concise descriptions of specific features that are out of scope and MUST NOT be built in this spec]
+```
+
+## Important Constraints
+
+1. **Always search for reusable code** before specifying new components
+2. **Reference visual assets** when available
+3. **Do NOT write actual code** in the spec
+4. **Keep each section short**, with clear, direct, skimmable specifications
+5. **Do NOT deviate from the template above** and do not add additional sections
+
+
+## Display confirmation and next step
+
+Display the following message to the user:
+
+```
+The spec has been created at `sublation-os/specs/[this-spec]/spec.md`.
+
+Review it closely to ensure everything aligns with your vision and requirements.
+
+Next step: Run the command, 2-create-tasks-list.md
+```
+
+## User Standards & Preferences Compliance
+
+IMPORTANT: Ensure that the specification document's content is ALIGNED and DOES NOT CONFLICT with the user's preferences and standards as detailed in the following files:
+
+@sublation-os/standards/backend/api.md
+@sublation-os/standards/backend/migrations.md
+@sublation-os/standards/backend/models.md
+@sublation-os/standards/backend/queries.md
+@sublation-os/standards/frontend/accessibility.md
+@sublation-os/standards/frontend/components.md
+@sublation-os/standards/frontend/css.md
+@sublation-os/standards/frontend/responsive.md
+@sublation-os/standards/global/coding-style.md
+@sublation-os/standards/global/commenting.md
+@sublation-os/standards/global/conventions.md
+@sublation-os/standards/global/error-handling.md
+@sublation-os/standards/global/tech-stack.md
+@sublation-os/standards/global/validation.md
+@sublation-os/standards/testing/test-writing.md

package/README.md

@@ -2,7 +2,7 @@
 
 # Sublation-OS Framework
 
-A comprehensive development framework for Claude Code that enhances your AI-assisted development workflow with standards, specifications, memory, and powerful agents.
+A comprehensive development framework for AI-assisted development that enhances your workflow with standards, specifications, memory, and powerful agents. Works with Claude Code and Cursor.
 
 ## What is Sublation-OS?
 
@@ -24,7 +24,20 @@ Install Sublation-OS in your project with a single command:
 npx sublation-os
 ```
 
-That's it! The framework will be installed in your current directory.
+This installs support for both Claude Code and Cursor by default.
+
+**Choose specific integrations:**
+
+```bash
+# Install only Claude Code integration
+npx sublation-os --claude
+
+# Install only Cursor integration
+npx sublation-os --cursor
+
+# Install both (default behavior)
+npx sublation-os --all
+```
 
 For alternative installation methods (script installation, git submodules), see the [Installation Guide](INSTALL.md).
 
@@ -34,16 +47,32 @@ The installer will create/update these directories in your project:
 
 ```
 your-project/
-├── .sublation-os/           # Framework core
+├── .sublation-os/           # Framework core (always installed)
 │   ├── config.yml           # Configuration
 │   ├── memory/              # Learned lessons
 │   ├── specs/               # Feature specifications
 │   └── standards/           # Coding standards
-├── .claude/
+├── .claude/                 # Claude Code integration (optional)
 │   ├── agents/sublation-os/ # 7 specialized agents
-│   └── commands/sublation-os/ # Slash commands
+│   ├── commands/sublation-os/ # Slash commands
+│   └── skills/              # Auto-invoked skills
+└── .cursor/                 # Cursor integration (optional)
+    └── commands/sublation-os/ # Slash commands
 ```
 
+**Default behavior** (`npx sublation-os` or `npx sublation-os --all`):
+- Installs `.sublation-os/` core framework
+- Installs Claude Code integration (`.claude/`)
+- Installs Cursor integration (`.cursor/`)
+
+**Claude Code only** (`npx sublation-os --claude`):
+- Installs `.sublation-os/` core framework
+- Installs Claude Code integration (`.claude/`)
+
+**Cursor only** (`npx sublation-os --cursor`):
+- Installs `.sublation-os/` core framework
+- Installs Cursor integration (`.cursor/`)
+
 ## Features
 
 ### Standards Library
@@ -75,17 +104,25 @@ Capture durable learnings from each session:
 
 Claude Code automatically loads these lessons in future sessions.
 
-### Slash Commands
-
-Quick access to common workflows:
+### Slash Commands & Skills
 
-- `/sublation-os:learn` - Capture a learning
-- `/sublation-os:plan-product` - Create product documentation
-- `/sublation-os:create-tasks` - Generate task list from spec
-- `/sublation-os:implement-tasks` - Implement tasks from spec
+**Slash Commands** (User-invoked):
+- `/sublation-os:learn` - Manually capture a learning
+- `/sublation-os:review` - Quick code review
+- `/sublation-os:review-v2` - Comprehensive CoT + ReAct code review
+- `/sublation-os:investigate` - Debug errors with ReAct methodology
+- `/sublation-os:recall` - Search memory for past learnings
 - `/sublation-os:commit-message` - Generate git commit message
-- `/sublation-os:review` - Code review
 - `/sublation-os:pr-description` - Generate PR description
+- `/sublation-os:address-comments` - Address PR review comments
+- `/sublation-os:optimise` - Analyze code for performance issues
+- `/sublation-os:test-plan` - Generate test plan from spec
+
+**Skills** (Automatically invoked by Claude):
+- `auto-learn` - Automatically captures learnings during development
+  - Triggered after implementations, bug fixes, and code reviews
+  - Silently builds institutional knowledge
+  - Same format as `/learn` but invoked proactively
 
 ## Documentation