@mytechtoday/augment-extensions 0.1.0

package/modules/workflows/beads/rules/workflow.md

@@ -0,0 +1,285 @@
+# Beads Workflow Guide
+
+## Overview
+
+Beads provides a git-backed issue tracker optimized for AI agents. Issues are stored as JSONL (JSON Lines) in `.beads/issues.jsonl`, making them version-controlled, mergeable, and agent-readable.
+
+## Core Workflow
+
+```
+┌─────────────────┐
+│ Create Task     │
+│ bd create       │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Add Dependencies│
+│ bd dep add      │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Find Ready Tasks│
+│ bd ready        │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Work on Task    │
+│ bd comment      │
+└────────┬────────┘
+         │
+         ▼
+┌─────────────────┐
+│ Close Task      │
+│ bd close        │
+└─────────────────┘
+```
+
+## Step 1: Initialize Beads
+
+### With CLI
+
+```bash
+cd your-project
+bd init
+```
+
+This creates:
+- `.beads/issues.jsonl` - Issue storage
+- `.beads/config.json` - Configuration
+- Updates `AGENTS.md` with Beads instructions
+
+### Without CLI
+
+Create the directory structure manually:
+
+```bash
+mkdir .beads
+touch .beads/issues.jsonl
+echo '{"version": "1.0"}' > .beads/config.json
+```
+
+Add to `AGENTS.md`:
+
+```markdown
+# Beads Task Tracking
+
+This project uses Beads for task tracking. Issues are stored in `.beads/issues.jsonl`.
+
+## Workflow
+1. Create tasks by appending to `.beads/issues.jsonl`
+2. Use hash-based IDs: `bd-<hash>`
+3. Track dependencies with `blocks` and `blocked_by` fields
+4. Mark tasks closed with `status: "closed"`
+```
+
+## Step 2: Create Tasks
+
+### With CLI
+
+```bash
+# Create a P0 task
+bd create "Implement user authentication" -p 0
+
+# Create with description
+bd create "Add login endpoint" -p 1 -d "POST /api/auth/login with email/password"
+
+# Create subtask
+bd create "Add password hashing" -p 1 --parent bd-a3f8.1
+```
+
+### Without CLI
+
+Append JSON to `.beads/issues.jsonl`:
+
+```json
+{"id":"bd-a1b2","title":"Implement user authentication","status":"open","priority":0,"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+```
+
+### AI Agent Pattern
+
+Ask your AI:
+
+```
+Create a Beads task for implementing user authentication with priority 0
+```
+
+The AI will either:
+- Run `bd create` if CLI is available
+- Append to `.beads/issues.jsonl` if working manually
+
+## Step 3: Add Dependencies
+
+### With CLI
+
+```bash
+# Task bd-b2c3 blocks task bd-a1b2
+bd dep add bd-a1b2 bd-b2c3
+
+# View dependencies
+bd show bd-a1b2
+```
+
+### Without CLI
+
+Update the issue in `.beads/issues.jsonl`:
+
+```json
+{"id":"bd-a1b2","title":"Implement user authentication","status":"open","priority":0,"blocks":["bd-b2c3"],"created":"2024-01-20T10:00:00Z","updated":"2024-01-20T10:00:00Z"}
+```
+
+### Dependency Types
+
+- **blocks** - This task blocks another task
+- **blocked_by** - This task is blocked by another task
+- **related** - Related but not blocking
+- **parent** - Parent task (for hierarchical IDs)
+
+## Step 4: Find Ready Tasks
+
+### With CLI
+
+```bash
+# List tasks with no open blockers
+bd ready
+
+# List all open tasks
+bd list
+
+# Filter by priority
+bd list -p 0
+```
+
+### Without CLI
+
+Parse `.beads/issues.jsonl` to find tasks where:
+- `status` is `"open"`
+- `blocked_by` is empty or all blockers are closed
+
+### AI Agent Pattern
+
+Ask your AI:
+
+```
+What Beads tasks are ready to work on?
+```
+
+The AI will:
+- Run `bd ready` if CLI available
+- Parse `.beads/issues.jsonl` manually otherwise
+
+## Step 5: Work on Task
+
+### With CLI
+
+```bash
+# Add comment
+bd comment bd-a1b2 "Started implementation, added login endpoint"
+
+# Update status
+bd update bd-a1b2 --status in-progress
+
+# Add labels
+bd update bd-a1b2 --labels backend,auth
+```
+
+### Without CLI
+
+Append update to `.beads/issues.jsonl`:
+
+```json
+{"id":"bd-a1b2","title":"Implement user authentication","status":"in-progress","priority":0,"comments":[{"text":"Started implementation","timestamp":"2024-01-20T11:00:00Z"}],"updated":"2024-01-20T11:00:00Z"}
+```
+
+## Step 6: Close Task
+
+### With CLI
+
+```bash
+bd close bd-a1b2
+```
+
+### Without CLI
+
+Update status in `.beads/issues.jsonl`:
+
+```json
+{"id":"bd-a1b2","title":"Implement user authentication","status":"closed","priority":0,"closed":"2024-01-20T12:00:00Z","updated":"2024-01-20T12:00:00Z"}
+```
+
+## Essential Commands
+
+### With CLI
+
+| Command | Action |
+|---------|--------|
+| `bd create "Title" -p 0` | Create P0 task |
+| `bd ready` | List tasks with no blockers |
+| `bd list` | List all open tasks |
+| `bd show <id>` | View task details |
+| `bd dep add <child> <parent>` | Add dependency |
+| `bd comment <id> "Text"` | Add comment |
+| `bd close <id>` | Close task |
+| `bd compact` | Summarize old closed tasks |
+
+### Without CLI
+
+All operations are manual edits to `.beads/issues.jsonl`. See `file-format.md` for JSONL structure.
+
+## Advanced Features
+
+### Hierarchical Tasks
+
+Create epic/task/subtask structure:
+
+```bash
+# Create epic
+bd create "User Management" -p 0
+# Returns: bd-a3f8
+
+# Create task under epic
+bd create "Add authentication" -p 1 --parent bd-a3f8
+# Returns: bd-a3f8.1
+
+# Create subtask
+bd create "Hash passwords" -p 2 --parent bd-a3f8.1
+# Returns: bd-a3f8.1.1
+```
+
+### Stealth Mode
+
+Use Beads without committing to main repo:
+
+```bash
+bd init --stealth
+```
+
+This creates `.beads/` in a separate branch that doesn't merge to main.
+
+### Compaction
+
+Summarize old closed tasks to save context:
+
+```bash
+bd compact
+```
+
+This uses AI to create semantic summaries of closed tasks, reducing context window usage.
+
+## Best Practices
+
+1. **Use Descriptive Titles**: Clear, specific task names
+2. **Set Priorities**: P0 (critical) to P3 (nice-to-have)
+3. **Track Dependencies**: Use `bd dep add` to show relationships
+4. **Add Comments**: Document progress and decisions
+5. **Close Promptly**: Mark tasks closed when done
+6. **Compact Regularly**: Run `bd compact` to manage context
+
+## Next Steps
+
+- See `file-format.md` for JSONL structure
+- See `manual-setup.md` for CLI-free setup
+- See `best-practices.md` for advanced patterns
+

package/modules/workflows/openspec/README.md

@@ -0,0 +1,96 @@
+# OpenSpec Workflow Module
+
+**Spec-driven development (SDD) for AI coding assistants.**
+
+## Overview
+
+OpenSpec provides a structured workflow for managing changes in AI-assisted development. It ensures humans and AI agents agree on specifications before implementation, reducing rework and improving code quality.
+
+## Key Benefits
+
+- **Alignment Before Implementation**: Agree on specs before writing code
+- **Structured Change Management**: Proposals, specs, and tasks in organized folders
+- **Brownfield-Friendly**: Excellent for modifying existing features (1→n), not just greenfield (0→1)
+- **Version Controlled**: All specs stored in git alongside code
+- **AI Agent Compatible**: Works with any tool that reads AGENTS.md
+
+## Installation Options
+
+### Option 1: With CLI (Recommended)
+
+Install the OpenSpec CLI for full features:
+
+```bash
+# npm
+npm install -g @fission-ai/openspec@latest
+
+# Nix
+nix run github:Fission-AI/OpenSpec -- init
+
+# Initialize in your project
+cd your-project
+openspec init
+```
+
+**Benefits**: Validation, archiving, slash commands, auto-generated AGENTS.md
+
+### Option 2: Without CLI (Manual)
+
+Follow the workflow manually without installing the CLI. See `rules/manual-setup.md` for instructions.
+
+**Benefits**: No installation required, works immediately
+
+**Limitations**: No validation, manual archiving, no slash commands
+
+## Directory Structure
+
+```
+your-project/
+├── openspec/
+│   ├── AGENTS.md              # AI agent instructions (auto-generated)
+│   ├── project.md             # Project context and conventions
+│   ├── specs/                 # Current specifications (source of truth)
+│   │   └── auth/
+│   │       └── spec.md
+│   └── changes/               # Proposed changes
+│       └── add-2fa/
+│           ├── proposal.md    # Why and what
+│           ├── tasks.md       # Implementation checklist
+│           ├── design.md      # Technical decisions (optional)
+│           └── specs/         # Spec deltas (changes)
+│               └── auth/
+│                   └── spec.md
+```
+
+## Workflow
+
+See `rules/workflow.md` for complete workflow documentation.
+
+**Quick Summary**:
+
+1. **Draft Proposal** - Create change proposal with AI
+2. **Review & Align** - Iterate on specs until agreement
+3. **Implement** - AI implements tasks referencing specs
+4. **Archive** - Merge approved changes into source specs
+
+## Character Count
+
+This module contains comprehensive OpenSpec workflow documentation that exceeds the standard `.augment/` folder character limit.
+
+**Total**: ~25,000 characters across all rule files
+
+## Contents
+
+- `rules/workflow.md` - Complete workflow guide
+- `rules/spec-format.md` - Specification format and delta syntax
+- `rules/manual-setup.md` - Manual setup without CLI
+- `rules/commands.md` - CLI command reference
+- `rules/best-practices.md` - Tips and patterns
+- `examples/` - Example specs and changes
+
+## Learn More
+
+- **Homepage**: https://openspec.dev/
+- **GitHub**: https://github.com/Fission-AI/OpenSpec
+- **Documentation**: See `rules/` directory in this module
+

package/modules/workflows/openspec/examples/complete-change-example.md

@@ -0,0 +1,230 @@
+# Complete OpenSpec Change Example
+
+This example shows a complete OpenSpec change from start to finish.
+
+## Scenario
+
+Adding two-factor authentication (2FA) to an existing authentication system.
+
+## Directory Structure
+
+```
+openspec/
+├── specs/
+│   └── auth/
+│       └── spec.md                    # Existing auth spec
+└── changes/
+    └── add-2fa/
+        ├── proposal.md                # Why we need 2FA
+        ├── tasks.md                   # Implementation steps
+        └── specs/
+            └── auth/
+                └── spec.md            # Changes to auth spec
+```
+
+## File: proposal.md
+
+```markdown
+# Add Two-Factor Authentication
+
+## Motivation
+
+Users have requested stronger account security. Password-only authentication
+is insufficient for protecting sensitive user data. Industry best practices
+recommend 2FA for all accounts.
+
+## Changes
+
+1. Add OTP (One-Time Password) generation and verification
+2. Modify login flow to require 2FA after password verification
+3. Add user settings for 2FA enrollment and recovery codes
+4. Add audit logging for 2FA events
+
+## Impact
+
+### Breaking Changes
+- All users will be required to enroll in 2FA on next login
+- Login API response changes to include 2FA challenge
+
+### Database Changes
+- Add `otp_secret` column to users table
+- Create `otp_verification_logs` table
+- Add `recovery_codes` table
+
+### Frontend Changes
+- New OTP input component
+- Updated login flow with 2FA step
+- New 2FA settings page
+
+## Timeline
+
+- Database migration: 1 day
+- Backend implementation: 2-3 days
+- Frontend implementation: 2-3 days
+- Testing and rollout: 1 week
+
+## Dependencies
+
+- TOTP library (e.g., pyotp, speakeasy)
+- QR code generation library
+```
+
+## File: tasks.md
+
+```markdown
+# Implementation Tasks
+
+## 1. Database Setup
+- [ ] 1.1 Add `otp_secret` column to users table (nullable initially)
+- [ ] 1.2 Create `otp_verification_logs` table with columns:
+  - id, user_id, success, ip_address, timestamp
+- [ ] 1.3 Create `recovery_codes` table with columns:
+  - id, user_id, code_hash, used, created_at
+- [ ] 1.4 Write and test migration script
+- [ ] 1.5 Add database indexes for performance
+
+## 2. Backend Implementation
+- [ ] 2.1 Install TOTP library dependency
+- [ ] 2.2 Create OTP service with methods:
+  - generate_secret()
+  - generate_qr_code(secret)
+  - verify_otp(secret, code)
+- [ ] 2.3 Add POST /api/auth/2fa/enroll endpoint
+  - Generates secret and QR code
+  - Returns QR code and recovery codes
+- [ ] 2.4 Add POST /api/auth/2fa/verify endpoint
+  - Verifies OTP code
+  - Issues JWT on success
+- [ ] 2.5 Modify POST /api/auth/login endpoint
+  - Return 2FA challenge instead of JWT
+  - Include temporary token for 2FA verification
+- [ ] 2.6 Add rate limiting to verification endpoint (3 attempts per 5 minutes)
+- [ ] 2.7 Add audit logging for all 2FA events
+- [ ] 2.8 Write unit tests for OTP service
+- [ ] 2.9 Write integration tests for 2FA endpoints
+
+## 3. Frontend Implementation
+- [ ] 3.1 Create OTPInput component
+  - 6-digit input with auto-focus
+  - Paste support
+  - Error state display
+- [ ] 3.2 Create 2FAEnrollment component
+  - Display QR code
+  - Show recovery codes
+  - Confirmation step
+- [ ] 3.3 Update LoginForm component
+  - Handle 2FA challenge response
+  - Show OTP input after password verification
+- [ ] 3.4 Create 2FASettings page
+  - Enable/disable 2FA
+  - Regenerate recovery codes
+  - View 2FA status
+- [ ] 3.5 Add 2FA status indicator to user profile
+- [ ] 3.6 Write component tests
+
+## 4. Documentation
+- [ ] 4.1 Update API documentation
+- [ ] 4.2 Create user guide for 2FA enrollment
+- [ ] 4.3 Create admin guide for 2FA management
+- [ ] 4.4 Update security documentation
+
+## 5. Testing & Rollout
+- [ ] 5.1 End-to-end testing
+- [ ] 5.2 Security review
+- [ ] 5.3 Performance testing
+- [ ] 5.4 Staged rollout plan
+- [ ] 5.5 Monitor error rates and user feedback
+```
+
+## File: specs/auth/spec.md (Delta)
+
+```markdown
+# Delta for Auth Specification
+
+## ADDED Requirements
+
+### Requirement: Two-Factor Authentication
+The system MUST require a second factor (OTP) during login for all users.
+
+#### Scenario: 2FA enrollment
+- GIVEN a user without 2FA enabled
+- WHEN the user accesses the 2FA settings page
+- THEN a QR code is generated
+- AND recovery codes are displayed
+- AND the user must verify an OTP to complete enrollment
+
+#### Scenario: Login with 2FA
+- GIVEN a user with 2FA enabled
+- WHEN the user submits valid credentials
+- THEN a 2FA challenge is returned
+- AND a temporary token is issued (valid for 5 minutes)
+- AND no JWT is issued until OTP verification
+
+#### Scenario: Valid OTP
+- GIVEN a user has received a 2FA challenge
+- WHEN the user submits a valid OTP within 5 minutes
+- THEN a JWT is issued
+- AND the user is logged in
+- AND the verification is logged
+
+#### Scenario: Invalid OTP
+- GIVEN a user has received a 2FA challenge
+- WHEN the 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 temporary token is invalidated
+
+#### Scenario: Expired 2FA challenge
+- GIVEN a user has received a 2FA challenge
+- WHEN more than 5 minutes have passed
+- THEN the temporary token is invalid
+- AND the user must restart the login process
+
+### Requirement: Recovery Codes
+The system MUST provide recovery codes for account recovery.
+
+#### Scenario: Generate recovery codes
+- WHEN a user enrolls in 2FA
+- THEN 10 recovery codes are generated
+- AND codes are displayed once
+- AND codes are hashed before storage
+
+#### Scenario: Use recovery code
+- GIVEN a user cannot access their OTP device
+- WHEN the user submits a valid recovery code
+- THEN the code is marked as used
+- AND 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 password and 2FA verification.
+
+#### Scenario: Valid credentials (MODIFIED)
+- WHEN a user submits valid credentials
+- THEN if 2FA is enabled, a 2FA challenge is returned (CHANGED)
+- AND if 2FA is disabled, a JWT is returned (CHANGED)
+- AND the login attempt is logged
+
+## REMOVED Requirements
+
+(None for this change)
+```
+
+## After Implementation
+
+Once all tasks are complete, archive the change:
+
+### With CLI
+```bash
+openspec archive add-2fa --yes
+```
+
+### Without CLI
+1. Copy the delta from `openspec/changes/add-2fa/specs/auth/spec.md`
+2. Apply ADDED/MODIFIED sections to `openspec/specs/auth/spec.md`
+3. Move `openspec/changes/add-2fa/` to `openspec/archive/add-2fa/`
+
+The source spec now includes all 2FA requirements as the new source of truth.
+

package/modules/workflows/openspec/module.json

@@ -0,0 +1,53 @@
+{
+  "name": "openspec-workflow",
+  "version": "1.0.0",
+  "displayName": "OpenSpec Workflow",
+  "description": "Spec-driven development (SDD) workflow for AI coding assistants. Provides structured change management with proposals, specs, and tasks.",
+  "type": "workflow",
+  "author": "Augment Extensions",
+  "license": "MIT",
+  "keywords": [
+    "openspec",
+    "spec-driven-development",
+    "sdd",
+    "workflow",
+    "planning",
+    "specifications",
+    "change-management"
+  ],
+  "augment": {
+    "characterCount": 30509,
+    "priority": "high",
+    "category": "workflow",
+    "compatibleWith": [
+      "Claude Code",
+      "CodeBuddy",
+      "Cursor",
+      "GitHub Copilot",
+      "Continue",
+      "Windsurf",
+      "All AGENTS.md compatible tools"
+    ]
+  },
+  "dependencies": {},
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Fission-AI/OpenSpec"
+  },
+  "documentation": {
+    "homepage": "https://openspec.dev/",
+    "installation": "https://github.com/Fission-AI/OpenSpec#install--initialize",
+    "workflow": "https://github.com/Fission-AI/OpenSpec#create-your-first-change"
+  },
+  "installation": {
+    "required": false,
+    "optional": true,
+    "methods": {
+      "npm": "npm install -g @fission-ai/openspec@latest",
+      "nix": "nix run github:Fission-AI/OpenSpec -- init",
+      "manual": "Follow manual setup instructions in rules/manual-setup.md"
+    },
+    "notes": "CLI installation is optional. AI agents can follow the workflow manually without the CLI, but the CLI provides validation, archiving, and slash commands."
+  }
+}
+