@mytechtoday/augment-extensions 0.1.0

package/modules/workflows/openspec/rules/best-practices.md

@@ -0,0 +1,272 @@
+# OpenSpec Best Practices
+
+## Change Management
+
+### Keep Changes Atomic
+
+✅ **Good**: One focused change per folder
+```
+openspec/changes/add-2fa/
+openspec/changes/add-profile-search/
+```
+
+❌ **Bad**: Multiple unrelated changes in one folder
+```
+openspec/changes/misc-improvements/  # Too vague
+```
+
+### Use Descriptive Names
+
+✅ **Good**: Clear, specific names
+- `add-2fa`
+- `fix-login-timeout`
+- `refactor-auth-flow`
+
+❌ **Bad**: Generic or cryptic names
+- `feature-123`
+- `updates`
+- `fix`
+
+### Review Before Implementation
+
+Always review and iterate on specs before coding:
+
+1. Create proposal and specs
+2. Review with stakeholders
+3. Refine until agreement
+4. Then implement
+
+**Why**: Catching issues in specs is 10x cheaper than in code.
+
+## Specification Writing
+
+### Be Specific
+
+✅ **Good**: Concrete, testable requirements
+```markdown
+### Requirement: Session Timeout
+The system SHALL terminate sessions after 30 minutes of inactivity.
+
+#### Scenario: Inactive session
+- GIVEN a user is logged in
+- WHEN 30 minutes pass with no activity
+- THEN the session is terminated
+- AND the user is redirected to login
+```
+
+❌ **Bad**: Vague requirements
+```markdown
+### Requirement: Security
+The system should be secure.
+```
+
+### Include Edge Cases
+
+✅ **Good**: Cover error scenarios
+```markdown
+#### Scenario: Invalid OTP
+- WHEN a user submits an invalid OTP
+- THEN an error message is displayed
+- AND the user can retry up to 3 times
+- AND after 3 failures, the account is locked
+
+#### Scenario: Expired OTP
+- WHEN a user submits an expired OTP (>5 minutes old)
+- THEN an error message is displayed
+- AND a new OTP can be requested
+```
+
+### Use Consistent Language
+
+- **SHALL** - Mandatory requirement
+- **MUST** - Mandatory requirement (stronger emphasis)
+- **SHOULD** - Recommended but not mandatory
+- **MAY** - Optional feature
+
+## Task Management
+
+### Break Down Large Tasks
+
+✅ **Good**: Granular, actionable tasks
+```markdown
+## 2. Backend Implementation
+- [ ] 2.1 Create OTP model with secret and expiry fields
+- [ ] 2.2 Add OTP generation function using TOTP algorithm
+- [ ] 2.3 Add OTP verification function with rate limiting
+- [ ] 2.4 Update login endpoint to require OTP
+- [ ] 2.5 Add OTP enrollment endpoint
+```
+
+❌ **Bad**: Vague, large tasks
+```markdown
+## 2. Backend
+- [ ] 2.1 Implement 2FA
+```
+
+### Group Related Tasks
+
+Organize tasks by phase or component:
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column
+- [ ] 1.2 Add OTP logs table
+- [ ] 1.3 Create migration
+
+## 2. Backend API
+- [ ] 2.1 OTP generation endpoint
+- [ ] 2.2 OTP verification endpoint
+
+## 3. Frontend UI
+- [ ] 3.1 OTP input component
+- [ ] 3.2 Update login flow
+```
+
+### Update Tasks During Implementation
+
+If scope changes during implementation, update tasks.md:
+
+```markdown
+## 2. Backend Implementation
+- [x] 2.1 Create OTP model
+- [x] 2.2 Add OTP generation
+- [ ] 2.3 Add OTP verification
+- [ ] 2.4 Add rate limiting (ADDED during implementation)
+```
+
+## Multi-Spec Changes
+
+### When Changes Affect Multiple Components
+
+Create deltas for each affected spec:
+
+```
+openspec/changes/add-user-roles/
+├── proposal.md
+├── tasks.md
+└── specs/
+    ├── auth/
+    │   └── spec.md      # Auth changes
+    ├── users/
+    │   └── spec.md      # User model changes
+    └── permissions/
+        └── spec.md      # Permission system changes
+```
+
+### Reference Dependencies
+
+In proposal.md, note cross-component dependencies:
+
+```markdown
+## Dependencies
+- Auth spec changes depend on User model changes
+- Permission checks require Auth changes to be complete
+```
+
+## Archiving
+
+### Archive Promptly
+
+Don't let completed changes accumulate in `openspec/changes/`:
+
+```bash
+# With CLI
+openspec archive add-2fa --yes
+
+# Without CLI - move to archive
+mv openspec/changes/add-2fa openspec/archive/
+```
+
+### Keep Archive Organized
+
+Archive folder structure:
+
+```
+openspec/archive/
+├── 2024-01-add-2fa/
+├── 2024-01-profile-search/
+└── 2024-02-role-permissions/
+```
+
+Consider adding date prefixes for chronological ordering.
+
+## Project Context
+
+### Keep project.md Updated
+
+Update `openspec/project.md` when:
+- Tech stack changes
+- New conventions are adopted
+- Architecture evolves
+- New guidelines are established
+
+### Include Examples
+
+Add examples to project.md:
+
+```markdown
+## Naming Conventions
+
+### API Endpoints
+- Use kebab-case: `/api/user-profiles`
+- Use plural nouns: `/api/users` not `/api/user`
+- Version with prefix: `/api/v1/users`
+
+### Database Tables
+- Use snake_case: `user_profiles`
+- Use plural nouns: `users` not `user`
+```
+
+## AI Agent Collaboration
+
+### Provide Context
+
+When asking AI to create changes:
+
+```
+Create an OpenSpec change for adding role-based permissions.
+Context: We have 3 roles (admin, editor, viewer) and need to restrict
+access to certain API endpoints based on role.
+```
+
+### Iterate on Specs
+
+Don't accept first draft:
+
+```
+The spec looks good, but can you add scenarios for:
+1. What happens when a user has multiple roles?
+2. How do we handle role changes for active sessions?
+```
+
+### Reference Existing Specs
+
+When implementing:
+
+```
+Please implement the tasks in openspec/changes/add-roles/tasks.md
+Make sure to follow the patterns established in openspec/specs/auth/spec.md
+```
+
+## Common Pitfalls
+
+### ❌ Skipping Spec Review
+
+Don't jump straight to implementation. Review specs first.
+
+### ❌ Vague Requirements
+
+Avoid "should work well" or "be fast". Be specific with numbers and behaviors.
+
+### ❌ Missing Scenarios
+
+Every requirement needs at least one scenario showing how it works.
+
+### ❌ Forgetting to Archive
+
+Clean up completed changes to keep the workspace organized.
+
+### ❌ Mixing Concerns
+
+Keep each change focused on one feature or fix.
+

package/modules/workflows/openspec/rules/manual-setup.md

@@ -0,0 +1,231 @@
+# OpenSpec Manual Setup (Without CLI)
+
+## Overview
+
+You can use the OpenSpec workflow without installing the CLI. This guide shows how to set up and use OpenSpec manually.
+
+## Initial Setup
+
+### 1. Create Directory Structure
+
+```bash
+mkdir -p openspec/specs
+mkdir -p openspec/changes
+mkdir -p openspec/archive
+```
+
+### 2. Create Project Context File
+
+Create `openspec/project.md`:
+
+```markdown
+# Project Context
+
+## Overview
+[Brief description of your project]
+
+## Tech Stack
+- Language: [e.g., TypeScript, Python]
+- Framework: [e.g., React, Django]
+- Database: [e.g., PostgreSQL, MongoDB]
+
+## Conventions
+- Code style: [e.g., ESLint, Black]
+- Testing: [e.g., Jest, pytest]
+- Naming: [e.g., camelCase for variables]
+
+## Architecture
+[High-level architecture notes]
+
+## Guidelines
+[Project-specific rules and patterns]
+```
+
+### 3. Create AGENTS.md Integration
+
+Add to your project's `AGENTS.md` (or create it):
+
+```markdown
+# OpenSpec Workflow
+
+This project uses OpenSpec for spec-driven development.
+
+## Directory Structure
+
+- `openspec/specs/` - Current specifications (source of truth)
+- `openspec/changes/` - Proposed changes (work in progress)
+- `openspec/archive/` - Completed changes
+- `openspec/project.md` - Project context and conventions
+
+## Workflow
+
+### Creating a Change
+
+1. Create a new folder: `openspec/changes/<change-name>/`
+2. Add `proposal.md` - Why and what
+3. Add `tasks.md` - Implementation checklist
+4. Add `specs/<component>/spec.md` - Spec deltas
+
+### Implementing a Change
+
+1. Read the spec deltas in `openspec/changes/<change-name>/specs/`
+2. Work through `tasks.md` sequentially
+3. Mark tasks complete: `- [x]` as you finish
+4. Reference specs when making implementation decisions
+
+### Archiving a Change
+
+1. Copy spec deltas to `openspec/specs/`
+2. Apply ADDED/MODIFIED/REMOVED sections
+3. Move change folder to `openspec/archive/<change-name>/`
+
+## Spec Format
+
+See the spec format guide for details on writing specifications.
+
+### Delta Sections
+
+- `## ADDED Requirements` - New capabilities
+- `## MODIFIED Requirements` - Changed behavior
+- `## REMOVED Requirements` - Deprecated features
+
+### Requirement Format
+
+```markdown
+### Requirement: <Name>
+The system SHALL <requirement>.
+
+#### Scenario: <Name>
+- WHEN <condition>
+- THEN <result>
+```
+```
+
+### 4. Add to .gitignore (Optional)
+
+If you want to keep changes private:
+
+```bash
+echo "openspec/changes/" >> .gitignore
+```
+
+## Creating Your First Change
+
+### 1. Create Change Folder
+
+```bash
+mkdir -p openspec/changes/add-feature-x
+```
+
+### 2. Create Proposal
+
+Create `openspec/changes/add-feature-x/proposal.md`:
+
+```markdown
+# Add Feature X
+
+## Motivation
+[Why this change is needed]
+
+## Changes
+- [What will change]
+- [What components are affected]
+
+## Impact
+- [Breaking changes]
+- [Migration requirements]
+- [Dependencies]
+```
+
+### 3. Create Tasks
+
+Create `openspec/changes/add-feature-x/tasks.md`:
+
+```markdown
+## 1. [Phase Name]
+- [ ] 1.1 [Task description]
+- [ ] 1.2 [Task description]
+
+## 2. [Phase Name]
+- [ ] 2.1 [Task description]
+- [ ] 2.2 [Task description]
+```
+
+### 4. Create Spec Deltas
+
+Create `openspec/changes/add-feature-x/specs/<component>/spec.md`:
+
+```markdown
+# Delta for <Component>
+
+## ADDED Requirements
+
+### Requirement: <Name>
+The system SHALL <requirement>.
+
+#### Scenario: <Name>
+- WHEN <condition>
+- THEN <result>
+```
+
+## Working with AI Agents
+
+### Creating a Change
+
+Ask your AI:
+
+```
+Create a new OpenSpec change in openspec/changes/add-search-filters/ with:
+1. proposal.md explaining why we need search filters
+2. tasks.md with implementation steps
+3. specs/search/spec.md with the new requirements
+```
+
+### Implementing
+
+Ask your AI:
+
+```
+Please implement the tasks in openspec/changes/add-search-filters/tasks.md
+Reference the specs in openspec/changes/add-search-filters/specs/ for requirements
+Mark each task complete as you finish
+```
+
+### Archiving
+
+Ask your AI:
+
+```
+Please archive the add-search-filters change:
+1. Copy spec deltas from openspec/changes/add-search-filters/specs/ to openspec/specs/
+2. Apply the ADDED/MODIFIED/REMOVED sections to the source specs
+3. Move openspec/changes/add-search-filters/ to openspec/archive/
+```
+
+## Limitations Without CLI
+
+- ❌ No automatic validation
+- ❌ No slash commands (unless manually configured)
+- ❌ Manual archiving process
+- ❌ No auto-generated AGENTS.md updates
+
+## Benefits Without CLI
+
+- ✅ No installation required
+- ✅ Works immediately
+- ✅ Full control over file structure
+- ✅ Compatible with all AI agents
+- ✅ Simple git workflow
+
+## Upgrading to CLI Later
+
+If you decide to install the CLI later:
+
+```bash
+npm install -g @fission-ai/openspec@latest
+cd your-project
+openspec init
+```
+
+The CLI will detect your existing structure and integrate with it.
+

package/modules/workflows/openspec/rules/spec-format.md

@@ -0,0 +1,193 @@
+# OpenSpec Specification Format
+
+## Overview
+
+OpenSpec uses a structured markdown format for specifications. Specs live in two places:
+
+- **`openspec/specs/`** - Current specifications (source of truth)
+- **`openspec/changes/<change-name>/specs/`** - Proposed changes (deltas)
+
+## Spec Structure
+
+### Source Spec (openspec/specs/auth/spec.md)
+
+```markdown
+# Auth Specification
+
+## Purpose
+Authentication and session management.
+
+## Requirements
+
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN a JWT is returned
+- AND the JWT contains user ID and role
+
+#### Scenario: Invalid credentials
+- WHEN a user submits invalid credentials
+- THEN an error is returned
+- AND no JWT is issued
+```
+
+### Delta Spec (openspec/changes/add-2fa/specs/auth/spec.md)
+
+```markdown
+# Delta for Auth
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor during login.
+
+#### Scenario: OTP required
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required
+- AND the OTP is sent to the user's registered device
+
+#### Scenario: Valid OTP
+- WHEN a user submits a valid OTP
+- THEN a JWT is issued
+- AND the user is logged in
+
+## MODIFIED Requirements
+
+### Requirement: User Authentication
+The system SHALL issue a JWT on successful login after two-factor verification.
+
+#### Scenario: Valid credentials
+- WHEN a user submits valid credentials
+- THEN an OTP challenge is required (CHANGED)
+- AND no JWT is issued until OTP verification (ADDED)
+
+## REMOVED Requirements
+
+(None for this change)
+```
+
+## Delta Format Rules
+
+### Section Headers
+
+Use these exact headers in delta specs:
+
+- `## ADDED Requirements` - New capabilities
+- `## MODIFIED Requirements` - Changed behavior
+- `## REMOVED Requirements` - Deprecated features
+
+### Requirement Format
+
+```markdown
+### Requirement: <Name>
+The system SHALL/MUST/SHOULD <requirement text>.
+
+#### Scenario: <Scenario Name>
+- WHEN <condition>
+- THEN <expected behavior>
+- AND <additional expectation>
+```
+
+### Keywords
+
+- **SHALL** - Mandatory requirement
+- **MUST** - Mandatory requirement (stronger)
+- **SHOULD** - Recommended but not mandatory
+- **MAY** - Optional
+
+### Scenario Format
+
+Use Given-When-Then style:
+
+- **GIVEN** - Initial context (optional)
+- **WHEN** - Action or condition
+- **THEN** - Expected result
+- **AND** - Additional conditions/results
+
+## Example: Complete Change
+
+### Proposal (openspec/changes/add-2fa/proposal.md)
+
+```markdown
+# Add Two-Factor Authentication
+
+## Motivation
+Users need stronger account security. Passwords alone are insufficient.
+
+## Changes
+- Add OTP generation and verification
+- Modify login flow to require 2FA
+- Add user settings for 2FA enrollment
+
+## Impact
+- Breaking change: All users must enroll in 2FA
+- Database migration required
+- Frontend login flow changes
+```
+
+### Tasks (openspec/changes/add-2fa/tasks.md)
+
+```markdown
+## 1. Database Setup
+- [ ] 1.1 Add OTP secret column to users table
+- [ ] 1.2 Create OTP verification logs table
+- [ ] 1.3 Add migration script
+
+## 2. Backend Implementation
+- [ ] 2.1 Add OTP generation endpoint
+- [ ] 2.2 Modify login flow to require OTP
+- [ ] 2.3 Add OTP verification endpoint
+- [ ] 2.4 Add 2FA enrollment endpoint
+
+## 3. Frontend Updates
+- [ ] 3.1 Create OTP input component
+- [ ] 3.2 Update login flow UI
+- [ ] 3.3 Add 2FA settings page
+```
+
+### Spec Delta (openspec/changes/add-2fa/specs/auth/spec.md)
+
+See example above in "Delta Spec" section.
+
+## Archiving Process
+
+When archiving, the delta is applied to the source spec:
+
+1. **ADDED** sections are appended to source spec
+2. **MODIFIED** sections replace existing requirements
+3. **REMOVED** sections are deleted from source spec
+
+Result: `openspec/specs/auth/spec.md` now includes 2FA requirements.
+
+## Best Practices
+
+1. **One Spec Per Component**: Don't mix auth and profile specs
+2. **Complete Scenarios**: Every requirement needs at least one scenario
+3. **Clear Language**: Use SHALL/MUST for clarity
+4. **Atomic Changes**: Each delta should be independently reviewable
+5. **Update Existing**: Use MODIFIED for changes, not ADDED + REMOVED
+
+## Validation
+
+### With CLI
+
+```bash
+openspec validate <change-name>
+```
+
+Checks:
+- Required headers present
+- Requirement format correct
+- Scenario format valid
+- No orphaned scenarios
+
+### Without CLI
+
+Manual checklist:
+- [ ] All deltas have ADDED/MODIFIED/REMOVED sections
+- [ ] Every requirement has a scenario
+- [ ] Keywords (SHALL/MUST) used correctly
+- [ ] Scenarios follow WHEN/THEN format
+