@mytechtoday/augment-extensions 1.2.2 → 1.3.1

package/augment-extensions/workflows/openspec/rules/best-practices.md

@@ -1,272 +0,0 @@
-# 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/augment-extensions/workflows/openspec/rules/manual-setup.md

@@ -1,231 +0,0 @@
-# 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.
-