@ekkos/cli 0.2.0

package/templates/skills/permissions/Skill.md

@@ -0,0 +1,322 @@
+---
+name: permissions
+description: Manage ekkOS tool permissions. View, grant, or revoke permissions for proactive tool execution. Use when user types "/permissions" or wants to configure what ekkOS can do automatically.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# /permissions - Manage ekkOS Tool Permissions
+
+Control what ekkOS tools can run proactively without asking for approval.
+
+## Usage
+
+```bash
+/permissions                    # Show current permissions
+/permissions list               # Show all permissions
+/permissions grant <scope>      # Grant a permission
+/permissions revoke <scope>     # Revoke a permission
+/permissions reset              # Reset to defaults
+```
+
+## Permission Scopes
+
+### 🔍 ekkOS_Search (Low Risk)
+```bash
+/permissions grant search:auto_before_answer
+  → Automatically search memory before answering technical questions
+
+/permissions grant search:auto_on_debug
+  → Automatically search for similar issues when debugging
+```
+
+### 🔨 ekkOS_Forge (Medium Risk)
+```bash
+/permissions grant forge:auto_on_fix
+  → Automatically create patterns when you fix bugs
+
+/permissions grant forge:auto_on_solution
+  → Create patterns for any non-trivial solution you provide
+```
+
+### 📋 ekkOS_Directive (Medium Risk)
+```bash
+/permissions grant directive:auto_capture_preferences
+  → Automatically save user preferences as directives
+
+/permissions grant directive:auto_capture_corrections
+  → Save corrections as directives without asking
+```
+
+### 📊 ekkOS_Track (Low Risk)
+```bash
+/permissions grant track:auto_track_usage
+  → Automatically track when patterns are applied
+
+/permissions grant track:auto_track_outcomes
+  → Track success/failure of pattern applications
+```
+
+### ⚠️ ekkOS_Conflict (Low Risk)
+```bash
+/permissions grant conflict:auto_check_destructive
+  → Automatically check for conflicts before dangerous operations
+```
+
+### 🧠 ekkOS_Recall (Low Risk)
+```bash
+/permissions grant recall:auto_load_context
+  → Automatically load relevant past context for tasks
+```
+
+## Risk Levels
+
+| Level | Operations | Examples |
+|-------|------------|----------|
+| **Low** | Read-only, no side effects | Search, Recall, Conflict checks |
+| **Medium** | Write operations, reversible | Forge patterns, Create directives |
+| **High** | Destructive, irreversible | (None currently - all high-risk requires explicit approval) |
+
+## Implementation
+
+When user runs `/permissions`:
+
+### Step 1: Parse Command
+
+```bash
+#!/bin/bash
+ARGS="${ARGUMENTS:-list}"
+API_KEY=$(jq -r '.apiKey // .hookApiKey' ~/.ekkos/config.json)
+BASE_URL="https://api.ekkos.dev"
+
+case "$ARGS" in
+  ""|list)
+    # Show current permissions
+    curl -s "$BASE_URL/api/v1/permissions" \
+      -H "Authorization: Bearer $API_KEY" | jq .
+    ;;
+
+  grant*)
+    # Extract scope from "grant scope:name"
+    SCOPE=$(echo "$ARGS" | sed 's/grant //')
+    curl -s "$BASE_URL/api/v1/permissions/grant" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "{\"scope\": \"$SCOPE\"}" | jq .
+    ;;
+
+  revoke*)
+    # Extract scope from "revoke scope:name"
+    SCOPE=$(echo "$ARGS" | sed 's/revoke //')
+    curl -s "$BASE_URL/api/v1/permissions/revoke" \
+      -H "Authorization: Bearer $API_KEY" \
+      -H "Content-Type: application/json" \
+      -d "{\"scope\": \"$SCOPE\"}" | jq .
+    ;;
+
+  reset)
+    # Reset to recommended defaults
+    curl -s "$BASE_URL/api/v1/permissions/reset" \
+      -H "Authorization: Bearer $API_KEY" \
+      -X POST | jq .
+    ;;
+
+  *)
+    echo "Unknown command: $ARGS"
+    echo "Usage: /permissions [list|grant|revoke|reset]"
+    exit 1
+    ;;
+esac
+```
+
+### Step 2: Display Results
+
+Format the response for readability:
+
+```
+✓ ekkOS Tool Permissions
+
+## Active Permissions (5)
+
+🔍 ekkOS_Search
+  ✓ auto_before_answer        [low risk]    Used: 247 times
+  ✓ auto_on_debug              [low risk]    Used: 18 times
+
+🔨 ekkOS_Forge
+  ✓ auto_on_fix                [medium risk] Used: 42 times
+
+📋 ekkOS_Directive
+  ✓ auto_capture_preferences   [medium risk] Used: 9 times
+
+## Revoked Permissions (1)
+
+🔨 ekkOS_Forge
+  ✗ auto_on_solution           [medium risk] Revoked 3 days ago
+
+## Available Permissions
+
+You can grant these additional permissions:
+
+  /permissions grant track:auto_track_usage
+  /permissions grant recall:auto_load_context
+  /permissions grant conflict:auto_check_destructive
+
+Run "/permissions grant <scope>" to enable.
+```
+
+### Step 3: Recommend Defaults
+
+If user has NO permissions set, show recommended starter set:
+
+```
+🚀 Recommended Starter Permissions
+
+These are safe, read-only operations that make ekkOS smarter:
+
+  /permissions grant search:auto_before_answer      ← Search memory first
+  /permissions grant track:auto_track_usage         ← Track what works
+  /permissions grant conflict:auto_check_destructive ← Safety checks
+
+Would you like to grant all three? (y/n)
+```
+
+## Permission Enforcement
+
+The MCP gateway checks permissions before executing tools:
+
+```typescript
+// Before executing a tool
+const hasPermission = await checkPermission(
+  userId,
+  toolName,
+  context.permission_scope
+);
+
+if (!hasPermission) {
+  // Ask user for approval
+  return {
+    success: false,
+    error: 'Permission required',
+    request_permission: {
+      tool: toolName,
+      scope: context.permission_scope,
+      description: 'What this allows...',
+      risk_level: 'low'
+    }
+  };
+}
+
+// Execute tool with permission
+await executeTool(toolName, args);
+await trackPermissionUsage(userId, toolName, scope);
+```
+
+## Examples
+
+### Example 1: First Time User
+
+```
+User: /permissions
+
+Output:
+  ✓ ekkOS Tool Permissions
+
+  You haven't granted any permissions yet.
+
+  🚀 Recommended Starter Set (read-only, safe):
+
+    /permissions grant search:auto_before_answer
+    /permissions grant track:auto_track_usage
+    /permissions grant conflict:auto_check_destructive
+
+  Or grant all at once:
+
+    /permissions reset    ← Sets recommended defaults
+```
+
+### Example 2: Grant Permission
+
+```
+User: /permissions grant forge:auto_on_fix
+
+Output:
+  ✓ Permission Granted
+
+  🔨 ekkOS_Forge: auto_on_fix [medium risk]
+
+  This allows:
+    - Automatically create memory patterns when you fix bugs
+    - Patterns are saved without asking for approval
+    - You can review patterns later with /patterns list
+
+  To revoke: /permissions revoke forge:auto_on_fix
+```
+
+### Example 3: View Active
+
+```
+User: /permissions list
+
+Output:
+  ✓ ekkOS Tool Permissions (6 active)
+
+  🔍 ekkOS_Search
+    ✓ auto_before_answer        Used 342 times   Last: 2 min ago
+    ✓ auto_on_debug              Used 29 times    Last: 1 hour ago
+
+  🔨 ekkOS_Forge
+    ✓ auto_on_fix                Used 67 times    Last: 5 min ago
+
+  📋 ekkOS_Directive
+    ✓ auto_capture_preferences   Used 14 times    Last: 1 day ago
+
+  📊 ekkOS_Track
+    ✓ auto_track_usage           Used 534 times   Last: 1 min ago
+    ✓ auto_track_outcomes        Used 67 times    Last: 10 min ago
+
+  Total proactive actions: 1,053
+```
+
+### Example 4: Revoke Permission
+
+```
+User: /permissions revoke forge:auto_on_fix
+
+Output:
+  ✓ Permission Revoked
+
+  🔨 ekkOS_Forge: auto_on_fix
+
+  This permission is now disabled. I will ask before creating patterns.
+
+  To re-enable: /permissions grant forge:auto_on_fix
+```
+
+## Integration with Skills
+
+When a skill wants to use a tool proactively:
+
+```markdown
+# In ekkOS_Learn skill
+
+Before calling ekkOS_Forge, check if permission is granted:
+
+1. Try proactive execution (relies on MCP gateway permission check)
+2. If rejected → explain what permission is needed
+3. Offer to grant permission: "/permissions grant forge:auto_on_solution"
+```
+
+## Success Metrics
+
+Permissions are working well when:
+- ✅ Users grant permissions for operations they trust
+- ✅ ekkOS operates autonomously within granted boundaries
+- ✅ Users rarely see "permission required" prompts for granted scopes
+- ✅ Permission usage stats show which features are most valuable
+- ✅ Users feel in control of what ekkOS can do automatically
+
+---
+
+**Mantra**: Explicit permissions enable proactive intelligence. Users control the autonomy level.

package/templates/spec-template.md

@@ -0,0 +1,159 @@
+# Feature Specification: [Feature Name]
+
+## Overview
+**Brief description of the feature and its purpose in the Echo ecosystem.**
+
+## User Stories
+
+### Primary User Story
+**As a [user type], I want [functionality] so that [benefit/value].**
+
+### Additional User Stories
+- **As a [user type], I want [functionality] so that [benefit/value].**
+- **As a [user type], I want [functionality] so that [benefit/value].**
+
+## Functional Requirements
+
+### Core Functionality
+1. **Requirement 1**: Description of what the system must do
+2. **Requirement 2**: Description of what the system must do
+3. **Requirement 3**: Description of what the system must do
+
+### AI Integration Requirements
+1. **AI Provider**: Which AI provider(s) will be used
+2. **Processing Pipeline**: How content flows through AI systems
+3. **Fallback Strategy**: What happens when AI fails
+4. **Cost Considerations**: Expected API usage and costs
+
+### Data Requirements
+1. **Input Data**: What data is required
+2. **Output Data**: What data is produced
+3. **Storage Requirements**: How data is persisted
+4. **Privacy Considerations**: Data handling and protection
+
+## Technical Requirements
+
+### API Design
+- **Endpoints**: List of required API endpoints
+- **Request/Response**: Data structures and validation
+- **Authentication**: Security requirements
+- **Rate Limiting**: Performance considerations
+
+### Database Schema
+- **Tables**: New or modified database tables
+- **Indexes**: Performance optimization requirements
+- **Migrations**: Database change requirements
+
+### Frontend Components
+- **UI Components**: New or modified React components
+- **State Management**: Data flow and state handling
+- **User Experience**: Interaction patterns and flows
+
+## Non-Functional Requirements
+
+### Performance
+- **Response Time**: Expected API response times
+- **Throughput**: Expected request volume
+- **Scalability**: Growth and scaling considerations
+
+### Reliability
+- **Uptime**: Availability requirements
+- **Error Handling**: Error scenarios and recovery
+- **Monitoring**: Observability and alerting
+
+### Security
+- **Authentication**: User verification requirements
+- **Authorization**: Access control requirements
+- **Data Protection**: Privacy and security measures
+
+## Acceptance Criteria
+
+### Functional Acceptance
+- [ ] **Criterion 1**: Specific, testable requirement
+- [ ] **Criterion 2**: Specific, testable requirement
+- [ ] **Criterion 3**: Specific, testable requirement
+
+### Technical Acceptance
+- [ ] **Criterion 1**: Performance or technical requirement
+- [ ] **Criterion 2**: Performance or technical requirement
+- [ ] **Criterion 3**: Performance or technical requirement
+
+### AI Acceptance
+- [ ] **Criterion 1**: AI accuracy or quality requirement
+- [ ] **Criterion 2**: AI performance requirement
+- [ ] **Criterion 3**: AI reliability requirement
+
+## Dependencies
+
+### Internal Dependencies
+- **Feature A**: Required for this feature to work
+- **Feature B**: Required for this feature to work
+
+### External Dependencies
+- **API Service**: External service requirements
+- **AI Provider**: AI service requirements
+- **Third-party Library**: Library requirements
+
+## Risks and Mitigations
+
+### Technical Risks
+- **Risk 1**: Description and mitigation strategy
+- **Risk 2**: Description and mitigation strategy
+
+### AI Risks
+- **Risk 1**: AI accuracy or availability risk
+- **Risk 2**: AI cost or performance risk
+
+### Business Risks
+- **Risk 1**: User adoption or satisfaction risk
+- **Risk 2**: Competitive or market risk
+
+## Implementation Plan
+
+### Phase 1: Foundation
+- [ ] **Task 1**: Description and estimated effort
+- [ ] **Task 2**: Description and estimated effort
+
+### Phase 2: Core Implementation
+- [ ] **Task 1**: Description and estimated effort
+- [ ] **Task 2**: Description and estimated effort
+
+### Phase 3: Integration and Testing
+- [ ] **Task 1**: Description and estimated effort
+- [ ] **Task 2**: Description and estimated effort
+
+## Success Metrics
+
+### User Metrics
+- **Metric 1**: How success will be measured
+- **Metric 2**: How success will be measured
+
+### Technical Metrics
+- **Metric 1**: Performance or reliability metric
+- **Metric 2**: Performance or reliability metric
+
+### AI Metrics
+- **Metric 1**: AI accuracy or quality metric
+- **Metric 2**: AI cost or efficiency metric
+
+## Review and Acceptance Checklist
+
+### Specification Review
+- [ ] **Requirement Completeness**: All requirements clearly defined
+- [ ] **Technical Feasibility**: Implementation approach validated
+- [ ] **AI Integration**: AI capabilities and limitations understood
+- [ ] **User Experience**: UX flow and interactions defined
+
+### Technical Review
+- [ ] **Architecture Alignment**: Fits with existing system architecture
+- [ ] **Performance Impact**: Performance implications understood
+- [ ] **Security Review**: Security implications addressed
+- [ ] **Scalability**: Growth and scaling considerations addressed
+
+### Business Review
+- [ ] **User Value**: Clear value proposition for users
+- [ ] **Resource Requirements**: Development effort and costs estimated
+- [ ] **Timeline**: Realistic implementation timeline
+- [ ] **Success Criteria**: Clear definition of success
+
+