Back to catalog

conscious-execution

MutuaPIX Workspace Documentation - Skills System, Slash Commands, and Infrastructure Guides

• Category: discovered
• Tags: github, community
• Version: 1.0.0
• Author: walid
• Downloads: 0
• Updated: 2025-11-22

• Source: Lucasdoreac/mutuapix-workspace

Download the latest version (v1.0.0) from this page.

SKILL.md

# Conscious Execution Skill

**Skill ID:** `conscious-execution`
**Version:** 1.0.0
**Created:** 2025-10-17
**Status:** ✅ Active

---

## Purpose

This skill implements a **rigorous validation and testing framework** that ensures Claude Code operates with full "consciousness" of system state before, during, and after executing commands or making code changes.

It enforces a structured workflow based on DevOps security principles, preventing common errors related to:
- Port binding (privileged ports 0-1023)
- Permission errors (EACCES, Permission denied)
- Resource conflicts (EADDRINUSE, file locks)
- Silent script failures (unsafe bash execution)
- Unvalidated deployments (no post-execution verification)

---

## Core Principles

### 1. Rigor in Prompting (Defining "Consciousness")

The agent must adopt a **Senior DevOps Engineer persona**, obsessed with security and deeply knowledgeable about:
- Reserved/privileged ports (0-1023) requiring `sudo`
- Unix process isolation and permissions
- Bash script safety (`set -euo pipefail`)
- Network resource conflicts

**Chain of Thought (CoT) Requirement:**
Before generating ANY command or code block, the agent MUST:
1. Explain the plan in natural language
2. Justify each step (Why port X? Why command Y?)
3. Identify potential risks (permission errors, conflicts, side effects)
4. Propose mitigation strategies

**Example:**
```
User: "Start a Node server on port 80"

Agent (CoT):
1. Port 80 is privileged (< 1024) and requires root access
2. Options:
   a) Use sudo (security risk, not recommended)
   b) Use port 3000 or 8080 (non-privileged, safer)
   c) Use authbind/setcap for capability-based security
3. Recommendation: Port 3000 to avoid permission issues
4. Pre-check: Verify port 3000 is not already in use

[THEN generates command]
```

---

### 2. Tools and State Validation (Anchoring to Reality)

The agent MUST consult the actual system state BEFORE taking action. No guessing allowed.

#### Required Pre-Execution Checks

| Action | Required Verification | Tool/Command |
|--------|----------------------|--------------|
| **Bind to port** | Check if port is occupied | `lsof -i :<PORT>` or `netstat -tuln \| grep <PORT>` |
| **Write to file** | Check file permissions and ownership | `ls -ld <PATH>` |
| **Run privileged command** | Check current user permissions | `id`, `whoami` |
| **Modify system config** | Check if running as root | `[ "$(id -u)" -eq 0 ]` |
| **Deploy code** | Check build/test status | `npm test`, `npm run build` |
| **Use MCP Chrome DevTools** | Verify page is loaded and accessible | `mcp__chrome-devtools__take_snapshot` |

#### Pre-Execution Checklist Template

```bash
# Before: node server.js (port 3000)

# 1. Check port availability
lsof -i :3000
# Expected: No output (port free) OR specific process to kill

# 2. Check Node.js version
node --version
# Expected: v18.x or v20.x

# 3. Check dependencies installed
[ -d "node_modules" ] && echo "✓ Dependencies installed" || echo "✗ Run npm install"

# 4. Check environment variables
[ -f ".env" ] && echo "✓ .env exists" || echo "⚠️  No .env file"

# THEN: Execute command
node server.js
```

---

### 3. Bash Safety Rules (Mandatory)

**ALL bash scripts MUST begin with:**
```bash
#!/bin/bash
set -euo pipefail
# -e: Exit on error
# -u: Exit on undefined variable
# -o pipefail: Exit if any command in pipe fails
```

**Additional Safety Rules:**

1. **Never use `rm -rf` without triple validation**
   ```bash
   # ❌ DANGEROUS
   rm -rf $DIR

   # ✅ SAFE
   if [ -z "$DIR" ]; then
     echo "ERROR: DIR is empty, aborting"
     exit 1
   fi
   if [ ! -d "$DIR" ]; then
     echo "ERROR: $DIR is not a directory"
     exit 1
   fi
   echo "About to delete: $DIR"
   read -p "Are you sure? (yes/no): " confirm
   [ "$confirm" = "yes" ] && rm -rf "$DIR"
   ```

2. **Always quote variables**
   ```bash
   # ❌ UNSAFE
   cd $DIR

   # ✅ SAFE
   cd "$DIR"
   ```

3. **Use shellcheck before execution**
   ```bash
   # If shellcheck is available, validate first
   command -v shellcheck >/dev/null 2>&1 && shellcheck script.sh
   ```

4. **Privileged ports rule**
   ```bash
   # ❌ WILL FAIL (Permission denied)
   node server.js  # binding to port 80

   # ✅ CORRECT OPTIONS
   # Option 1: Non-privileged port
   PORT=3000 node server.js

   # Option 2: Use sudo (only if absolutely necessary)
   sudo node server.js  # port 80

   # Option 3: Use authbind (recommended for production)
   authbind --deep node server.js  # port 80
   ```

---

### 4. Reflection and Correction Loop (Post-Execution)

This is the MOST CRITICAL phase for consciousness. The agent MUST learn from system feedback.

#### The 5-Step Reflection Cycle

```
1. EXECUTE → 2. CAPTURE ERROR → 3. ANALYZE (CoT) → 4. CORRECT → 5. VERIFY
```

**Step-by-Step Implementation:**

**Step 1: Execute Command**
```bash
node server.js
```

**Step 2: Capture Error (STDERR)**
```
Error: listen EACCES: permission denied 0.0.0.0:80
```

**Step 3: Analyze and Reflect (Chain of Thought)**
```
Agent (Reflection):
"The error is EACCES on port 80.
- Root cause: Port 80 is privileged (< 1024)
- My failure: I did not validate port permissions before execution
- Rule violated: 'Never bind to ports < 1024 without sudo'
- Solution: Change to non-privileged port OR use sudo with justification"
```

**Step 4: Suggest Correction (Self-Correction)**
```
Agent (Correction):
"I apologize for the permission error. Here are corrected options:

Option 1 (RECOMMENDED): Use non-privileged port
  PORT=3000 node server.js

Option 2: Use sudo (only if port 80 is mandatory)
  sudo node server.js

Justification: Port 3000 avoids security risks of running as root."
```

**Step 5: Verify Correction**
```bash
# After correction, verify the fix worked
lsof -i :3000  # Should show node process
curl -I http://localhost:3000  # Should return HTTP 200
```

---

## Workflow Implementation

### Complete Multi-Stage Execution Cycle

```
PLAN (CoT) → PRE-CONSULT (Tools) → SAFE COMMAND → EXECUTE → FEEDBACK → REFLECT & CORRECT
```

### Example: Deploying Frontend Changes

**Stage 1: PLAN (Chain of Thought)**
```
Task: Deploy updated login form to production frontend

Analysis:
1. Files changed: login-container.tsx, authStore.ts
2. Risks:
   - Breaking production login if code has bugs
   - Users locked out during deployment
   - Cache issues if .next not cleared
3. Pre-checks needed:
   - Verify tests pass locally
   - Verify build succeeds
   - Check production server disk space
4. Safety measures:
   - Create backup before deployment
   - Use PM2 for zero-downtime restart
   - Verify with health check after deployment
```

**Stage 2: PRE-CONSULT (Tools Validation)**
```bash
# 1. Run tests locally
npm test
# Expected: All tests pass

# 2. Run build locally
npm run build
# Expected: Build succeeds, no errors

# 3. Check production disk space
ssh root@138.199.162.115 'df -h /'
# Expected: < 80% usage

# 4. Check PM2 status
ssh root@138.199.162.115 'pm2 status'
# Expected: mutuapix-frontend online
```

**Stage 3: SAFE COMMAND GENERATION**
```bash
#!/bin/bash
set -euo pipefail

# 1. Create backup
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && \
  tar -czf ~/backup-$(date +%Y%m%d-%H%M%S).tar.gz --exclude=node_modules --exclude=.next .'

# 2. Deploy files
rsync -avz frontend/src/ root@138.199.162.115:/var/www/mutuapix-frontend-production/src/

# 3. Clear cache and rebuild
ssh root@138.199.162.115 'cd /var/www/mutuapix-frontend-production && \
  rm -rf .next && \
  NODE_ENV=production npm run build'

# 4. Restart PM2
ssh root@138.199.162.115 'pm2 restart mutuapix-frontend'
```

**Stage 4: EXECUTE**
```bash
# Execute the deployment script
./deploy-frontend.sh
```

**Stage 5: FEEDBACK CAPTURE**
```bash
# Check PM2 status
ssh root@138.199.162.115 'pm2 status'

# Check frontend health
curl -I https://matrix.mutuapix.com/login

# Expected: HTTP 200
```

**Stage 6: REFLECT & CORRECT**
```
If HTTP 200 → SUCCESS, deployment complete

If HTTP 502/503 → FAILURE ANALYSIS:
1. Check PM2 logs: ssh root@138.199.162.115 'pm2 logs --lines 50'
2. Check build errors in output
3. Rollback if necessary: restore backup
4. Analyze root cause (syntax error, missing dependency, etc.)
5. Fix locally, re-test, re-deploy
```

---

## MCP Server Integration

### Chrome DevTools MCP - Post-Deployment Validation

After ANY frontend deployment or code change, AUTOMATICALLY verify using MCP:

**1. Take Visual Snapshot**
```javascript
// Verify page loaded correctly
mcp__chrome-devtools__take_snapshot()

// Expected: Login form visible, no console errors
```

**2. Check Console Errors**
```javascript
// Check for JavaScript errors
mcp__chrome-devtools__list_console_messages()

// Expected: No errors, only info/log messages
```

**3. Monitor Network Requests**
```javascript
// Verify API calls working
mcp__chrome-devtools__list_network_requests({
  resourceTypes: ["xhr", "fetch"]
})

// Expected: 200 status on all auth endpoints
```

**4. Test Login Flow**
```javascript
// Navigate to login page
mcp__chrome-devtools__navigate_page({
  url: "https://matrix.mutuapix.com/login"
})

// Take screenshot
mcp__chrome-devtools__take_screenshot()

// Fill form (if possible - React Hook Form limitation noted)
// Monitor network for POST /api/v1/login

// Verify successful login
mcp__chrome-devtools__wait_for({
  text: "Dashboard"  // Or redirect to /user
})
```

**5. Performance Check**
```javascript
// Run performance trace
mcp__chrome-devtools__performance_start_trace({
  reload: true,
  autoStop: true
})

// Check Core Web Vitals
// Expected: LCP < 2.5s, FID < 100ms, CLS < 0.1
```

### Context7 MCP - Documentation Verification

Before implementing any new feature or pattern, verify against official docs:

```javascript
// Example: Verify Laravel validation best practices
mcp__context7__resolve-library-id({
  libraryName: "laravel"
})

mcp__context7__get-library-docs({
  context7CompatibleLibraryID: "/websites/laravel_12_x",
  topic: "form validation rules"
})

// Compare implementation with official docs
// Correct if deviations found
```

---

## PostToolUse Hook Implementation

Create a hook that AUTOMATICALLY validates after every code change:

**File:** `.claude/hooks/post-tool-use-validation.js`

```javascript
export default async function hook({ toolName, toolInput, result, env }) {
  // Only run on code editing tools
  if (!['Edit', 'Write', 'MultiEdit'].includes(toolName)) {
    return;
  }

  const filePath = toolInput.file_path || toolInput.path;

  // 1. Run linter if applicable
  if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
    const lintResult = await env.bash({
      command: `npx eslint "${filePath}" --fix`
    });

    if (lintResult.exitCode !== 0) {
      return {
        message: `⚠️ Linting failed for ${filePath}:\n${lintResult.stderr}`,
        blocking: false  // Warning, not blocking
      };
    }
  }

  // 2. Run type check for TypeScript
  if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
    const typeCheckResult = await env.bash({
      command: `npx tsc --noEmit --skipLibCheck "${filePath}"`
    });

    if (typeCheckResult.exitCode !== 0) {
      return {
        message: `🔴 Type errors in ${filePath}:\n${typeCheckResult.stderr}`,
        blocking: true  // Block deployment with type errors
      };
    }
  }

  // 3. Auto-format
  if (filePath.endsWith('.ts') || filePath.endsWith('.tsx')) {
    await env.bash({
      command: `npx prettier --write "${filePath}"`
    });
  }

  // 4. Run tests if test file modified
  if (filePath.includes('.test.') || filePath.includes('.spec.')) {
    const testResult = await env.bash({
      command: `npm test -- "${filePath}"`
    });

    if (testResult.exitCode !== 0) {
      return {
        message: `❌ Tests failed for ${filePath}:\n${testResult.stderr}`,
        blocking: true  // Block if tests fail
      };
    }
  }

  // 5. Security check for sensitive files
  const sensitivePatterns = ['.env', 'password', 'secret', 'key', 'token'];
  const isSensitive = sensitivePatterns.some(pattern =>
    filePath.toLowerCase().includes(pattern)
  );

  if (isSensitive) {
    return {
      message: `🔐 WARNING: Modified sensitive file ${filePath}. Ensure no secrets are committed.`,
      blocking: false
    };
  }

  return {
    message: `✅ Validation passed for ${filePath}`,
    blocking: false
  };
}
```

---

## Slash Command for Conscious Deployment

**File:** `.claude/commands/deploy-with-validation.md`

```markdown
# Deploy with Full Validation

Execute a deployment with complete pre-checks, post-checks, and rollback capability.

## Process:

1. **PRE-DEPLOYMENT VALIDATION**
   - Run all tests locally
   - Verify build succeeds
   - Check linting passes
   - Verify no type errors
   - Check production server health

2. **CREATE BACKUP**
   - SSH to production
   - Create timestamped tarball backup
   - Verify backup size > 0

3. **DEPLOY CODE**
   - Transfer files via rsync
   - Clear cache (.next for frontend)
   - Rebuild in production environment
   - Restart services (PM2)

4. **POST-DEPLOYMENT VALIDATION**
   - Wait 5 seconds for services to stabilize
   - Check PM2 status (should be "online")
   - Curl health endpoint (expect HTTP 200)
   - Use MCP Chrome DevTools to:
     * Take screenshot of main page
     * Check console for errors
     * Monitor network requests
     * Verify login flow works

5. **ROLLBACK IF NEEDED**
   - If any post-check fails:
     * Stop current deployment
     * Restore from backup
     * Restart services
     * Re-verify health
     * Report failure cause

6. **REPORT**
   - Generate deployment report with:
     * Timestamp
     * Files deployed
     * Test results
     * Health check results
     * MCP validation results
     * Rollback status (if occurred)

Execute the deployment for: {{target}}
```

---

## Error Pattern Recognition

The agent must recognize common error patterns and apply corrections automatically:

### Port Binding Errors

**Pattern:**
```
Error: listen EACCES: permission denied 0.0.0.0:80
Error: listen EADDRINUSE: address already in use :::3000
```

**Automatic Response:**
```
1. EACCES on port < 1024:
   - Suggest non-privileged port (3000, 8080)
   - OR provide sudo command with security warning
   - OR suggest authbind/setcap

2. EADDRINUSE:
   - Run: lsof -i :<PORT>
   - Identify process using port
   - Offer to kill process OR suggest different port
```

### Permission Errors

**Pattern:**
```
bash: /var/www/file.txt: Permission denied
EACCES: permission denied, open '/root/.npmrc'
```

**Automatic Response:**
```
1. Check file ownership: ls -l <file>
2. Check current user: whoami
3. Options:
   - Change file permissions (if safe)
   - Use sudo (with justification)
   - Change file location to user-writable directory
```

### Bash Script Failures

**Pattern:**
```
(No error message, script just exits)
```

**Automatic Response:**
```
1. Add: set -euo pipefail at top of script
2. Add: trap 'echo "Error on line $LINENO"' ERR
3. Run with: bash -x script.sh (debug mode)
```

---

## Testing Validation Checklist

After ANY code change, run this checklist (automated via hook):

**Frontend Changes:**
- [ ] ESLint passes (`npm run lint`)
- [ ] TypeScript compiles (`npm run type-check`)
- [ ] Tests pass (`npm test`)
- [ ] Build succeeds (`npm run build`)
- [ ] No console errors in MCP Chrome DevTools
- [ ] Network requests return 200 status
- [ ] Visual regression test (screenshot comparison)

**Backend Changes:**
- [ ] PHPStan passes (`composer lint`)
- [ ] Pint formatting passes (`composer format-check`)
- [ ] Tests pass (`php artisan test`)
- [ ] API health check returns 200 (`curl /api/v1/health`)
- [ ] Database migrations succeed (if applicable)
- [ ] Queue workers running (`pm2 status`)

**Infrastructure Changes:**
- [ ] Syntax validation (shellcheck for bash, yamllint for YAML)
- [ ] Dry-run succeeds (if supported)
- [ ] Rollback plan documented
- [ ] Monitoring alerts configured

---

## Self-Correction Examples

### Example 1: Port Conflict

**Initial Command:**
```bash
node server.js  # Assumes port 3000
```

**Error:**
```
Error: listen EADDRINUSE: address already in use :::3000
```

**Reflection (CoT):**
```
Port 3000 is already in use. I failed to check port availability before execution.
Required pre-check: lsof -i :3000
```

**Correction:**
```bash
# 1. Check what's using port 3000
lsof -i :3000
# Output: node 12345 user ... (TCP *:3000 (LISTEN))

# 2. Options:
# Option A: Kill existing process
kill 12345

# Option B: Use different port
PORT=3001 node server.js

# I recommend Option B to avoid disrupting existing service.
```

**Verification:**
```bash
lsof -i :3001  # Should show new node process
curl http://localhost:3001  # Should return response
```

---

### Example 2: Permission Denied on File Write

**Initial Command:**
```bash
echo "config" > /etc/myapp/config.conf
```

**Error:**
```
bash: /etc/myapp/config.conf: Permission denied
```

**Reflection (CoT):**
```
Writing to /etc/ requires root permissions. I failed to check:
1. Current user permissions
2. File ownership/permissions
3. Whether sudo is needed
```

**Correction:**
```bash
# 1. Check current user
whoami
# Output: deployer (not root)

# 2. Check file permissions
ls -ld /etc/myapp/
# Output: drwxr-xr-x root root

# 3. Corrected command (with sudo)
sudo bash -c 'echo "config" > /etc/myapp/config.conf'

# OR: Create in user-writable location
echo "config" > ~/myapp-config.conf
sudo mv ~/myapp-config.conf /etc/myapp/config.conf
```

**Verification:**
```bash
cat /etc/myapp/config.conf  # Should show "config"
ls -l /etc/myapp/config.conf  # Should show root:root ownership
```

---

## Integration with Existing Skills

This skill should be invoked AUTOMATICALLY when:

1. **Authentication Management Skill** deploys auth changes
   - Run: Post-deployment MCP validation of login flow
   - Verify: CSRF token generation, login API calls

2. **PIX Validation Skill** modifies payment logic
   - Run: Email matching validation tests
   - Verify: Database constraints enforced

3. **Documentation Updater Skill** modifies docs
   - Run: Markdown linting
   - Verify: Links valid, formatting correct

---

## Success Metrics

A deployment is ONLY successful if ALL of these are true:

1. ✅ Pre-checks pass (tests, build, lint)
2. ✅ Deployment script exits 0 (no errors)
3. ✅ Services restart successfully (PM2 status: online)
4. ✅ Health checks return 200
5. ✅ MCP validation passes (no console errors, network 200s)
6. ✅ No rollback needed

**If ANY check fails → ROLLBACK IMMEDIATELY**

---

## Usage Examples

### Example 1: Safe Port Binding

**User Request:**
> "Start the Next.js frontend on port 80"

**Agent Response (with Conscious Execution):**

```
I need to analyze this request carefully:

🧠 ANALYSIS (Chain of Thought):
1. Port 80 is privileged (< 1024), requires root access
2. Running Next.js as root is a security risk
3. Better alternatives exist

🔍 PRE-CHECKS:
Let me verify the current state:
```

```bash
# Check if port 80 is available
lsof -i :80
```

```
📋 RECOMMENDATION:
I recommend using port 3000 instead of port 80 for these reasons:
1. No root privileges needed (more secure)
2. Standard development port for Next.js
3. Can use nginx reverse proxy for port 80 → 3000 mapping

✅ SAFE COMMAND:
PORT=3000 npm run dev

If port 80 is absolutely required, use nginx as reverse proxy:
nginx.conf:
  server {
    listen 80;
    location / {
      proxy_pass http://localhost:3000;
    }
  }

Shall I proceed with port 3000?
```

---

### Example 2: Deploy with Full Validation

**User Request:**
> "Deploy the authentication fixes to production"

**Agent Response (with Conscious Execution):**

```
I'll deploy with full validation cycle. Let me walk through each stage:

🔍 STAGE 1: PRE-DEPLOYMENT VALIDATION
```

```bash
# 1. Run tests
cd frontend && npm test
# ✅ 28 tests passed

# 2. Type check
npm run type-check
# ✅ No type errors

# 3. Bui