Tutorial Overview
Series index: gstack Tutorial Series
Safety first: /careful, /freeze, /guard protect against accidents. Then coordinate parallel work with Conductor for 10-15 simultaneous agents.
What you will learn
- ✅
/carefuldestructive command warnings - ✅
/freezeedit lock to one directory - ✅
/guardcombined safety mode - ✅
/investigatesystematic debugging - ✅
/unfreezerelease the lock - ✅ Conductor parallel sprint coordination
Why Safety Guardrails?
The danger of powerful AI
flowchart LR
A[AI Agent] --> B[rm -rf]
B --> C[Files Gone]
C --> D[No Backup]
style B fill:#ffcccc
style D fill:#ffcccc
Protection layers
flowchart TD
A[User Request] --> B{Destructive?}
B -->|Yes| C[/careful Warning]
C --> D{User Confirm?}
D -->|No| E[Aborted]
D -->|Yes| F{In Freeze?}
F -->|Yes| G[/freeze Check]
G --> H{Right Directory?}
H -->|No| E
H -->|Yes| I[Execute]
F -->|No| I
style C fill:#fff3e0
style E fill:#e8f5e9
style G fill:#ffebee
/careful — Destructive Command Protection
What it blocks
| Command Category | Examples | Protection |
|---|---|---|
| File deletion | rm -rf, rmdir |
Requires confirmation |
| Database | DROP TABLE, DELETE FROM |
Requires confirmation |
| Git | git push --force, git reset --hard |
Requires confirmation |
| Environment | rm .env, truncate files |
Requires confirmation |
| System | sudo, chmod 777 |
Requires confirmation |
Usage
/careful
Output:
┌────────────────────────────────────────────┐
│ CAREFUL MODE ACTIVATED │
├────────────────────────────────────────────┤
│ Protected commands: │
│ ✅ rm -rf │
│ ✅ git push --force │
│ ✅ DROP TABLE │
│ ✅ DELETE FROM │
│ ✅ truncate │
│ ✅ sudo commands │
│ │
│ These commands will require confirmation. │
└────────────────────────────────────────────┘
Confirmation prompt
When a dangerous command is detected:
⚠️ DESTRUCTIVE COMMAND DETECTED
Command: rm -rf node_modules
This will permanently delete node_modules and all contents.
Type 'CONFIRM' to proceed, or 'CANCEL' to abort:
Always-on protection
/careful is enabled by default in gstack. Disable with:
/careful off
(Not recommended — safer to confirm each time)
/freeze — Directory Edit Lock
What it does
Locks all edits to a single directory. Prevents accidental changes outside the focus area.
Usage
/freeze src/auth
Output:
┌────────────────────────────────────────────┐
│ FREEZE ACTIVATED │
├────────────────────────────────────────────┤
│ Edit lock: src/auth/ │
│ │
│ All edits must be within: │
│ - src/auth/login.ts │
│ - src/auth/session.ts │
│ - src/auth/middleware.ts │
│ │
│ Blocked directories: │
│ ❌ src/api/ │
│ ❌ src/components/ │
│ ❌ tests/ │
│ ❌ Any other path │
│ │
│ Use /unfreeze to release. │
└────────────────────────────────────────────┘
When blocked
Attempting to edit outside freeze:
❌ FREEZE VIOLATION
Attempted edit: src/api/users.ts
Freeze locked to: src/auth/
The file src/api/users.ts is outside the frozen directory.
To edit this file:
1. /unfreeze to release current lock
2. /freeze src/api to lock to new directory
3. Or stay focused on src/auth/
Use cases
| Scenario | Why freeze |
|---|---|
| Bug investigation | Focus on affected module |
| Refactoring | Prevent scope creep |
| Feature work | Stay in your lane |
| Parallel agents | Each agent gets own directory |
/guard — Combined Safety
What it includes
/guard = /careful + /freeze
/guard src/auth
Output:
┌────────────────────────────────────────────┐
│ GUARD MODE ACTIVATED │
├────────────────────────────────────────────┤
│ 🔒 Edit lock: src/auth/ │
│ ⚠️ Destructive command protection: ON │
│ │
│ Full safety enabled: │
│ - Edits restricted to src/auth/ │
│ - Destructive commands require confirm │
│ - Git force operations blocked │
│ │
│ Use /unfreeze to release. │
└────────────────────────────────────────────┘
When to use
- Investigating production issues
- Working on critical code paths
- Parallel agent coordination
- Learning new codebase (prevents accidents)
/investigate — Systematic Debugging
What it does
- Auto-activates
/freezeto the affected directory - Traces the issue systematically
- Documents findings
- Proposes fixes with evidence
Usage
/investigate "Login fails silently for OAuth users"
Output:
Starting investigation: "Login fails silently for OAuth users"
┌────────────────────────────────────────────┐
│ INVESTIGATION MODE │
├────────────────────────────────────────────┤
│ 🔒 Auto-freeze: src/auth/ │
│ 📋 Hypothesis tracking: ON │
│ 📝 Evidence log: .gstack/investigate.md │
└────────────────────────────────────────────┘
Step 1: Reproduce the issue
─────────────────────────────
Testing OAuth login flow...
❌ Confirmed: Login returns 200 but session not created
User redirected to dashboard but shows as logged out
Step 2: Trace the code path
─────────────────────────────
src/auth/oauth.ts:45 → handleOAuthCallback()
src/auth/session.ts:23 → createSession()
⚠️ Found: createSession() called before user exists in DB
Step 3: Examine session creation
─────────────────────────────
src/auth/session.ts:23-35
```typescript
async function createSession(userId: string) {
const user = await getUser(userId); // Returns null if user not created yet
if (!user) {
return null; // Silent failure!
}
return Session.create(userId);
}
Step 4: Root cause identified ───────────────────────────── Issue: Race condition between OAuth callback and user creation
Timeline:
- OAuth provider returns success
- createSession() called immediately
- User record not yet inserted
- Session silently fails
- User redirected but not logged in
Step 5: Proposed fix ───────────────────────────── Option A: Await user creation before session (RECOMMENDED) Option B: Retry session creation with backoff Option C: Return explicit error instead of silent failure
Would you like me to implement Option A?
### Investigation log
All findings saved to `.gstack/investigate.md`:
```markdown
# Investigation: Login fails silently for OAuth users
Date: 2026-04-07
## Issue
Login returns 200 but session not created for OAuth users.
## Root Cause
Race condition in src/auth/session.ts:23
createSession() called before user record exists.
## Evidence
- Reproduced: Yes
- Affected files: src/auth/oauth.ts, src/auth/session.ts
- Traced path: oauth callback → session creation
## Fix Options
A) Await user creation (RECOMMENDED)
B) Retry with backoff
C) Explicit error
## Status
Awaiting user decision on fix approach.
/unfreeze — Release the Lock
Usage
/unfreeze
Output:
┌────────────────────────────────────────────┐
│ FREEZE RELEASED │
├────────────────────────────────────────────┤
│ Previous lock: src/auth/ │
│ │
│ All directories now editable. │
│ Destructive command protection: Still ON │
│ │
│ Use /freeze <dir> to lock again. │
└────────────────────────────────────────────┘
Conductor — Parallel Sprint Coordination
What it does
Coordinates 10-15 parallel Claude Code sessions working on different parts of the codebase.
Architecture
flowchart TD
A[Conductor] --> B[Agent 1: Auth]
A --> C[Agent 2: API]
A --> D[Agent 3: UI]
A --> E[Agent 4: Tests]
A --> F[Agent 5: Docs]
A --> G[... 10 more]
B --> H[src/auth/]
C --> I[src/api/]
D --> J[src/components/]
E --> K[tests/]
F --> L[docs/]
style A fill:#e1f5ff
Setup
/conductor start --agents 10
Output:
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR: PARALLEL SPRINT COORDINATION │
├─────────────────────────────────────────────────────────────┤
│ Agents: 10 │
│ Mode: Isolated (each has own worktree) │
│ │
│ Agent Assignments: │
│ ─────────────────────────────────────────────────────────────│
│ Agent 1: src/auth/ → Implement OAuth2 │
│ Agent 2: src/api/ → Add rate limiting │
│ Agent 3: src/components/ → Dashboard redesign │
│ Agent 4: tests/ → Auth test coverage │
│ Agent 5: docs/ → API documentation │
│ Agent 6: src/db/ → Migration scripts │
│ Agent 7: src/utils/ → Refactor helpers │
│ Agent 8: tests/ → Integration tests │
│ Agent 9: src/api/ → Endpoint validation │
│ Agent 10: src/auth/ → Session management │
│ │
│ Safety: Each agent frozen to assigned directory │
│ Communication: Shared task board at .gstack/tasks/ │
│ │
│ Commands: │
│ /conductor status - Check progress │
│ /conductor review <agent> - Review agent work │
│ /conductor merge - Merge completed work │
│ /conductor stop - End sprint │
└─────────────────────────────────────────────────────────────┘
Sprint started. Agents working in parallel.
Check status: /conductor status
Checking status
/conductor status
Output:
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR STATUS │
├─────────────────────────────────────────────────────────────┤
│ Sprint: feature/auth-system │
│ Duration: 2h 34m │
│ │
│ Agent Progress: │
│ ─────────────────────────────────────────────────────────────│
│ 1. Auth ████████████████████ 100% ✅ Complete │
│ 2. API ████████████████░░░░ 80% 🔄 Testing │
│ 3. UI ████████████████████ 100% ✅ Complete │
│ 4. Tests ████████████░░░░░░░░ 60% 🔄 In progress │
│ 5. Docs ████████████████████ 100% ✅ Complete │
│ 6. DB ████████████████████ 100% ✅ Complete │
│ 7. Utils ████████████████░░░░ 85% 🔄 Final touches │
│ 8. Tests ████████░░░░░░░░░░░░ 40% 🔄 In progress │
│ 9. API ████████████████████ 100% ✅ Complete │
│ 10. Auth ████████████████░░░░ 75% 🔄 Merging │
│ │
│ Summary: │
│ Complete: 5/10 │
│ In Progress: 5/10 │
│ Blocked: 0/10 │
│ │
│ Estimated completion: 45 minutes │
└─────────────────────────────────────────────────────────────┘
Reviewing agent work
/conductor review agent-2
Output:
┌─────────────────────────────────────────────────────────────┐
│ AGENT 2 REVIEW: API Rate Limiting │
├─────────────────────────────────────────────────────────────┤
│ Files changed: 4 │
│ Lines added: 127 │
│ Lines removed: 23 │
│ │
│ Changes: │
│ ─────────────────────────────────────────────────────────────│
│ src/api/middleware/rateLimit.ts (NEW) │
│ - Token bucket implementation │
│ - Per-IP and per-user limits │
│ - Redis-backed for distributed systems │
│ │
│ src/api/index.ts │
│ - Added rate limit middleware to all routes │
│ │
│ tests/api/rateLimit.test.ts (NEW) │
│ - Unit tests for token bucket │
│ - Integration tests for rate limiting │
│ │
│ docs/api/rate-limiting.md (NEW) │
│ - Usage documentation │
│ - Configuration options │
│ │
│ Review status: PENDING │
│ │
│ [A]pprove | [R]equest changes | [V]iew files │
└─────────────────────────────────────────────────────────────┘
Merging completed work
/conductor merge
Output:
Merging completed agent work...
┌─────────────────────────────────────────────────────────────┐
│ CONDUCTOR MERGE │
├─────────────────────────────────────────────────────────────┤
│ Checking for conflicts... │
│ ✅ No conflicts detected │
│ │
│ Merging in order: │
│ ─────────────────────────────────────────────────────────────│
│ 1. Agent 6 (DB) → base │
│ 2. Agent 1 (Auth) → merges cleanly │
│ 3. Agent 10 (Auth) → merges cleanly │
│ 4. Agent 9 (API) → merges cleanly │
│ 5. Agent 3 (UI) → merges cleanly │
│ 6. Agent 5 (Docs) → merges cleanly │
│ │
│ Remaining (not ready): │
│ - Agent 2 (API): 80% complete │
│ - Agent 4 (Tests): 60% complete │
│ - Agent 7 (Utils): 85% complete │
│ - Agent 8 (Tests): 40% complete │
│ │
│ ✅ Merged 6 agents to main │
│ │
│ Run tests before continuing: │
│ npm test │
└─────────────────────────────────────────────────────────────┘
Voice Input Triggers
AquaVoice and Whisper friendly
Speak these phrases to trigger skills:
| Say This | Triggers |
|---|---|
| “be careful” | /careful |
| “freeze this directory” | /freeze <current> |
| “guard mode” | /guard <current> |
| “investigate this bug” | /investigate |
| “unfreeze” | /unfreeze |
| “start parallel sprint” | /conductor start |
| “check conductor status” | /conductor status |
Proactive Skill Suggestions
Context-aware recommendations
gstack suggests skills based on context:
┌────────────────────────────────────────────┐
│ SKILL SUGGESTION │
├────────────────────────────────────────────┤
│ Detected: Multiple failed login attempts │
│ │
│ Consider running: │
│ /investigate "auth failures" │
│ │
│ This will: │
│ - Freeze to src/auth/ │
│ - Trace the failure path │
│ - Document findings │
└────────────────────────────────────────────┘
Skill Quick Reference
| Command | Purpose | Scope |
|---|---|---|
/careful |
Destructive command protection | Global |
/careful off |
Disable protection | Not recommended |
/freeze <dir> |
Lock edits to directory | Specified dir |
/unfreeze |
Release directory lock | Global |
/guard <dir> |
Combined safety mode | Specified dir |
/investigate <issue> |
Systematic debugging | Auto-freeze |
/conductor start |
Start parallel sprint | Multi-agent |
/conductor status |
Check sprint progress | All agents |
/conductor merge |
Merge completed work | Ready agents |
Summary
Safety and parallel coordination in gstack provide:
- Destructive command protection — Think before you delete
- Directory freeze — Stay in your lane
- Combined guard mode — Maximum safety
- Systematic investigation — Debug with evidence
- Parallel sprints — 10-15 agents, one codebase
Key takeaways
- ✅ Keep
/carefulon always - ✅ Use
/freezewhen focused on one area - ✅ Use
/guardfor critical work - ✅ Use
/investigatefor complex bugs - ✅ Use Conductor for parallel feature development
Series navigation:
- ← Previous: Tutorial 11: Docs & Retro
- Back: Series Index