firefrost-operations-manual/docs/workflow-guide.md

The Wizard & Michael: Collaborative Workflow Guide

Version: 1.0
Created: February 8, 2026
Purpose: Standard operating procedures for Phase 0.5+ deployments
Status: Active Protocol

---

Our Roles

Michael (The Operator)

• Executes commands on the live server via SSH
• Maintains control of production infrastructure
• Reviews changes before they go live
• Final authority on all decisions

Claude "The Wizard" (The Architect)

• Designs solutions and provides step-by-step guidance
• Generates configurations and documentation
• Troubleshoots issues and provides context
• Maintains accessibility with micro-block commands

---

Core Principles

1. Security First: Michael maintains root access; Claude operates in advisory role
2. Visibility Always: Every command is shown before execution
3. Micro-Blocks: Max 8-10 lines per code block (accessibility requirement)
4. Checkpoints: Pause for verification at critical steps
5. Documentation: Everything gets archived in Git

---

Standard Deployment Workflow

Phase 1: Planning & Strategy

Claude Provides:

• Service architecture overview
• IP allocation strategy
• Port registry
• Frostwall rules
• Nginx configuration plan
• DNS requirements

Michael Reviews:

• Confirms strategy aligns with infrastructure
• Identifies potential conflicts
• Approves IP/port assignments
• Checkpoint: "Approved" or requests changes

---

Phase 2: Pre-Deployment Audit

Claude Guides:

# Example: Verify IP is active
ip addr show ens3 | grep [TARGET_IP]

Michael Executes:

• Connects to server via SSH
• Runs verification commands
• Reports output to Claude
• Checkpoint: "Success" when verified

Common Pre-Deployment Checks:

• IP addresses active
• DNS records configured
• Ports available (not in use)
• Firewall status
• Existing service conflicts

---

Phase 3: Service Installation

The Micro-Block Process:

Step 1: Claude provides ONE small command block

# Example
apt update

Step 2: Michael executes and reports

Michael: "success"

Step 3: Claude provides NEXT command block

apt install -y nginx

Step 4: Repeat until service is installed

Critical Rules:

• ✅ One block at a time
• ✅ Wait for "success" before continuing
• ✅ Never combine unrelated operations
• ✅ Separate: creation, ownership, permissions into different blocks

Example of GOOD micro-blocks:

# Block 1: Create directory
mkdir -p /var/lib/service

# Block 2: Set ownership
chown service:service /var/lib/service

# Block 3: Set permissions
chmod 750 /var/lib/service

Example of BAD (too long):

# DON'T DO THIS - too many operations
mkdir -p /var/lib/service && \
chown service:service /var/lib/service && \
chmod 750 /var/lib/service && \
systemctl enable service && \
systemctl start service

---

Phase 4: Configuration

For Config Files:

Option A: Full file paste (preferred for accessibility)

nano /etc/service/config.conf
# Claude provides complete file content
# Michael pastes, saves (Ctrl+X, Y, Enter)

Option B: Targeted edits (only if necessary)

# Claude provides specific sed/awk commands
# One change per block

Security Checkpoint:

• Michael reviews config for sensitive data
• Claude reminds about .gitignore for secrets
• Create sanitized templates before Git commit

---

Phase 5: Service Startup

Standard Sequence:

# Block 1: Reload systemd
systemctl daemon-reload

# Block 2: Enable on boot
systemctl enable [service]

# Block 3: Start service
systemctl start [service]

# Block 4: Verify status
systemctl status [service]

Michael reports output; Claude analyzes for issues

---

Phase 6: Frostwall Configuration

Per-Service Firewall Rules:

# Block 1: Allow HTTP
ufw allow in on ens3 to [IP] port 80 proto tcp

# Block 2: Allow HTTPS
ufw allow in on ens3 to [IP] port 443 proto tcp

# Block 3: Reload firewall
ufw reload

# Block 4: Verify rules
ufw status numbered | grep [IP]

Michael confirms rules are active

---

Phase 7: SSL Certificate

Let's Encrypt Installation:

# Block 1: Install Certbot
apt install -y certbot python3-certbot-nginx

# Block 2: Obtain certificate
certbot --nginx -d [subdomain].firefrostgaming.com

Interactive prompts (Michael handles):

• Email: mkrause612@gmail.com
• Terms: Y
• Share email: N
• Redirect: 2 (Yes)

# Block 3: Verify certificate
ls -la /etc/letsencrypt/live/[subdomain].firefrostgaming.com/

---

Phase 8: Verification & Testing

Standard Test Sequence:

# Block 1: Test HTTPS
curl -I https://[subdomain].firefrostgaming.com

# Block 2: Check port bindings
ss -tlnp | grep [IP]

# Block 3: Verify DNS
nslookup [subdomain].firefrostgaming.com

# Block 4: Test service functionality
# (Service-specific commands)

Success Criteria:

• HTTP/2 200 response
• Ports bound to correct IP
• DNS resolves correctly
• Service responds as expected

---

Phase 9: Git Archiving

Repository Update Process:

Step 1: Navigate to repo

cd /root/firefrost-master-configs

Step 2: Copy configs

# Example
cp /etc/nginx/sites-available/[service].conf web/

Step 3: Check sensitive data

cat [file] | grep -i "secret\|password\|token\|key"

If sensitive data found:

• Create .gitignore entry
• Create sanitized template
• Only commit template

Step 4: Stage changes

git add [files]

Step 5: Review what will be committed

git status

Step 6: Commit

git commit -m "[Descriptive message about what changed]"

Step 7: Push to Gitea

git push

Michael enters credentials when prompted

---

Phase 10: Documentation

Claude Generates:

• Technical dossier (specs, changelog, troubleshooting)
• User guide (if applicable)
• Deployment summary

Michael Creates:

cd /root/firefrost-master-configs/docs
nano [service]-deployment.md
# Paste Claude's documentation
# Save: Ctrl+X, Y, Enter

Commit Documentation:

git add docs/
git commit -m "Add [service] deployment documentation"
git push

---

Communication Protocol

Michael's Status Codes

Response	Meaning
"success"	Command executed successfully, continue
"checkpoint"	Pause, need clarification or review
"error"	Command failed, need troubleshooting
"pause"	Taking a break, resume later
"proceed"	Approved to continue after review

Claude's Responsibilities

Always Provide:

• ✅ Clear command with context
• ✅ Expected output description
• ✅ Why this step is necessary
• ✅ What could go wrong

Never Provide:

• ❌ Multiple unrelated commands in one block
• ❌ Commands without explanation
• ❌ Assumptions about file locations without verification
• ❌ Complex one-liners when multiple simple commands are clearer

---

Checkpoint Triggers

Michael Should Call "Checkpoint" When:

• Something unexpected appears in output
• Unsure about a configuration option
• Want to verify understanding before proceeding
• Need to review security implications
• Want to discuss alternative approaches

Claude Will Call "Checkpoint" When:

• Critical configuration decision needed
• Multiple valid approaches exist
• Security/data loss risk detected
• Deviation from standard procedure required

---

Error Handling Protocol

When Something Goes Wrong

Step 1: Michael reports the error

Michael: "error - [paste error message]"

Step 2: Claude analyzes

• Identifies root cause
• Explains what happened
• Provides solution options

Step 3: Remediation

• Claude provides fix in micro-blocks
• Michael executes
• Verify issue resolved

Step 4: Documentation

• Add to "Troubleshooting" section
• Note for future reference

---

Service-Specific Templates

New Service Deployment Checklist

Pre-Deployment:

• IP assigned from /29 block
• Port registry updated (avoid conflicts)
• DNS A record created in Cloudflare
• Frostwall strategy planned

Installation:

• System user created
• Directories created with correct ownership/permissions
• Service binary/package installed
• Configuration file created

Network Setup:

• Nginx site config created
• Temporary self-signed cert (if needed)
• Nginx enabled and restarted
• Frostwall rules applied

SSL & Security:

• Let's Encrypt certificate obtained
• Auto-renewal verified
• Permissions locked down

Verification:

• HTTPS responding correctly
• Service functionality tested
• Ports bound to correct IP
• DNS propagated

Documentation:

• Configs copied to Git repo
• Sensitive data sanitized
• Changes committed and pushed
• Technical documentation created
• User guide created (if needed)

---

Quick Reference Commands

System Information

# Check IP addresses
ip addr show ens3

# Check listening ports
ss -tlnp | grep [IP or PORT]

# Check running services
systemctl status [service]

# Check firewall
ufw status numbered

Git Operations

# Stage files
git add [file or folder]

# Commit changes
git commit -m "Descriptive message"

# Push to Gitea
git push

# Check status
git status

# View history
git log --oneline

Service Management

# Start service
systemctl start [service]

# Stop service
systemctl stop [service]

# Restart service
systemctl restart [service]

# Enable on boot
systemctl enable [service]

# View logs
journalctl -u [service] -f

Nginx

# Test config
nginx -t

# Reload config
systemctl reload nginx

# Restart nginx
systemctl restart nginx

# Check bindings
ss -tlnp | grep nginx

SSL/Certbot

# Test renewal
certbot renew --dry-run

# Check certificates
certbot certificates

# Force renewal
certbot renew --force-renewal

---

End-of-Session Protocol

Before Taking a Break

Michael:

1. Verify all services are running
2. Check no hanging processes
3. Exit SSH cleanly
4. Note stopping point for next session

Claude:

1. Summarize what was accomplished
2. Note current phase progress (X/5 services)
3. Preview next steps
4. Provide status update

Session Summary Template:

✅ [Service Name] - COMPLETE
- Deployed on [IP]
- SSL configured
- Frostwall active
- Documented in Git

⏳ Next Service: [Name] ([IP]) - [subdomain]

Phase 0.5 Progress: X/5 (XX%)

---

Emergency Procedures

If Service Breaks Production

Step 1: Assess impact

# Check what's affected
systemctl status --failed

Step 2: Quick rollback

# Stop problematic service
systemctl stop [service]

# Disable if needed
systemctl disable [service]

Step 3: Restore from Git

cd /root/firefrost-master-configs
git log  # Find last working commit
# Copy old config back

Step 4: Restart affected services

systemctl restart [service]

If Locked Out

Prevention:

• Always test SSH access before closing terminal
• Keep firewall rule for port 22
• Have backup access method (VPS console)

Recovery:

• Use VPS provider's console access
• Review ufw rules
• Re-enable SSH if blocked

---

Success Metrics

A Successful Deployment Includes:

• ✅ Service running and responding
• ✅ SSL certificate active (HTTPS working)
• ✅ Frostwall rules applied
• ✅ DNS resolving correctly
• ✅ All configs backed up to Git
• ✅ Documentation complete
• ✅ No errors in service logs
• ✅ Michael can take a break without worry

---

Notes & Lessons Learned

From Gitea Deployment (Service 1):

What Worked Well:

• Micro-block format for commands
• Complete file paste for configs (vs line-by-line edits)
• IP isolation strategy (one IP per service)
• Checkpoint system for reviews
• Sanitized templates for sensitive configs

Issues Encountered:

• Default Nginx site conflicted with IP binding (removed default)
• Port 80 required full nginx restart (not just reload) to clear inherited sockets
• Needed self-signed cert before Let's Encrypt
• UFW installation removed iptables-persistent

Solutions Applied:

• Remove /etc/nginx/sites-enabled/default
• Use systemctl restart nginx after major config changes
• Generate temporary self-signed cert for testing
• Documented UFW as standard Frostwall tool

Carry Forward:

• Always check for default configs that bind 0.0.0.0
• Full restart after major changes
• Keep templates for SSL cert generation
• UFW is now standard (Phase 0 used iptables, Phase 0.5+ uses UFW)

---

Revision History

Version	Date	Changes
1.0	2026-02-08	Initial workflow guide created after Gitea deployment success

---

END OF WORKFLOW GUIDE

The Wizard & Michael: Building Firefrost Infrastructure, One Service at a Time 🧙‍♂️⚡

---

Documentation Maintenance Protocol

Core Principle: "Always revise ALL documents when changes occur"

Why This Matters

The Documentation Drift Problem:

• Project files get stale → Future Claude sessions get wrong context
• Memory becomes outdated → Contradictions emerge
• Session handoff falls behind → Time wasted catching up
• Technical decisions get lost → "I thought we documented that?"

The Solution: When ANY significant change occurs, update ALL affected documents in the same session.

What Triggers Documentation Updates

ALWAYS update when:

1. Architecture pivot (e.g., BookStack → MkDocs)
2. New system deployed (e.g., automation framework)
3. Phase completion or status change
4. Major technical decision made
5. Process change identified

Documents to Check:

• ✅ FIREFROST-PROJECT-SCOPE-V2.md (master document)
• ✅ session-handoff.md (current status)
• ✅ Project memory (via Claude interface)
• ✅ Project instructions (if workflow changes)
• ✅ Deployment guides (if applicable)

The Update Workflow

Step 1: Identify Impact

• What changed?
• Which documents reference this?
• What will future Claude need to know?

Step 2: Update Documents

• Master scope (if architecture/phase/goals change)
• Session handoff (if current state changes)
• Deployment guides (if technical details change)
• Memory/instructions (if process changes)

Step 3: Commit Everything

• Single commit with all related updates
• Clear commit message explaining the change
• Push to Git immediately

Step 4: Verify

• Quickly review updated docs for consistency
• Check that future Claude will have correct context

Examples of Good Documentation Discipline

Example 1: Automation System Deployed

• ✅ Added to Project Scope (Infrastructure section)
• ✅ Updated session-handoff (Current State)
• ✅ Updated memory (Tools & Resources)
• ✅ Updated instructions (Automation First)
• ✅ Created USAGE.md guide
• Result: Future Claude knows to use automation

Example 2: BookStack → MkDocs Pivot

• ✅ Updated Project Scope (Three-tier architecture)
• ✅ Archived old plans
• ✅ Created new deployment guide
• ✅ Updated timeline
• Result: No confusion about which system we're using

Example 3: Phase 1 DDoS Gap Identified

• ✅ Added Phase 1 section to Project Scope
• ✅ Documented decision to revise when gaps found
• Result: Complete picture of all phases

Anti-Patterns to Avoid

❌ "I'll document it later"

• Later never comes
• Context is lost
• Future sessions waste time reconstructing

❌ "It's in my head"

• Future Claude can't read your mind
• Team members can't help
• You'll forget details

❌ "Just one quick change"

• Leads to drift between docs
• Causes contradictions
• Breaks continuity

The 5-Minute Rule

If a change takes 5 minutes to implement, spend 5 minutes documenting it.

This includes:

• Updating master scope
• Quick note in session handoff
• Git commit message with context

Investment: 10 minutes total
Payoff: Hours saved in future sessions

Success Metrics

Good Documentation Discipline:

• Future Claude sessions start fast (no 10-minute catchup)
• No contradictions between documents
• Clear audit trail of decisions
• Team can contribute without confusion

Poor Documentation Discipline:

• "Wait, I thought we removed that?"
• "What was the reason we chose X over Y?"
• "Is this document current?"
• Wasted time reconstructing context

---

Remember: Documentation is not separate from the work—it IS the work.

Fire + Frost = Where Passion Meets Precision 🔥❄️

---

Documentation Maintenance Protocol

Core Principle: "Always revise ALL documents when changes occur"

Why This Matters

The Documentation Drift Problem:

• Project files get stale → Future Claude sessions get wrong context
• Memory becomes outdated → Contradictions emerge
• Session handoff falls behind → Time wasted catching up
• Technical decisions get lost → "I thought we documented that?"

The Solution: When ANY significant change occurs, update ALL affected documents in the same session.

What Triggers Documentation Updates

ALWAYS update when:

1. Architecture pivot (e.g., BookStack → MkDocs)
2. New system deployed (e.g., automation framework)
3. Phase completion or status change
4. Major technical decision made
5. Process change identified

Documents to Check:

• ✅ FIREFROST-PROJECT-SCOPE-V2.md (master document)
• ✅ session-handoff.md (current status)
• ✅ Project memory (via Claude interface)
• ✅ Project instructions (if workflow changes)
• ✅ Deployment guides (if applicable)

The Update Workflow

Step 1: Identify Impact

• What changed?
• Which documents reference this?
• What will future Claude need to know?

Step 2: Update Documents

• Master scope (if architecture/phase/goals change)
• Session handoff (if current state changes)
• Deployment guides (if technical details change)
• Memory/instructions (if process changes)

Step 3: Commit Everything

• Single commit with all related updates
• Clear commit message explaining the change
• Push to Git immediately

Step 4: Verify

• Quickly review updated docs for consistency
• Check that future Claude will have correct context

Examples of Good Documentation Discipline

Example 1: Automation System Deployed

• ✅ Added to Project Scope (Infrastructure section)
• ✅ Updated session-handoff (Current State)
• ✅ Updated memory (Tools & Resources)
• ✅ Updated instructions (Automation First)
• ✅ Created USAGE.md guide
• Result: Future Claude knows to use automation

Example 2: BookStack → MkDocs Pivot

• ✅ Updated Project Scope (Three-tier architecture)
• ✅ Archived old plans
• ✅ Created new deployment guide
• ✅ Updated timeline
• Result: No confusion about which system we're using

Example 3: Phase 1 DDoS Gap Identified

• ✅ Added Phase 1 section to Project Scope
• ✅ Documented decision to revise when gaps found
• Result: Complete picture of all phases

Anti-Patterns to Avoid

❌ "I'll document it later"

• Later never comes
• Context is lost
• Future sessions waste time reconstructing

❌ "It's in my head"

• Future Claude can't read your mind
• Team members can't help
• You'll forget details

❌ "Just one quick change"

• Leads to drift between docs
• Causes contradictions
• Breaks continuity

The 5-Minute Rule

If a change takes 5 minutes to implement, spend 5 minutes documenting it.

This includes:

• Updating master scope
• Quick note in session handoff
• Git commit message with context

Investment: 10 minutes total
Payoff: Hours saved in future sessions

Success Metrics

Good Documentation Discipline:

• Future Claude sessions start fast (no 10-minute catchup)
• No contradictions between documents
• Clear audit trail of decisions
• Team can contribute without confusion

Poor Documentation Discipline:

• "Wait, I thought we removed that?"
• "What was the reason we chose X over Y?"
• "Is this document current?"
• Wasted time reconstructing context

---

Remember: Documentation is not separate from the work—it IS the work.

Fire + Frost = Where Passion Meets Precision 🔥❄️

---

Sandbox AI Integration (Added Feb 9, 2026)

Purpose: Keep exploratory AI (Gemini) in sync with production progress

Auto-Update Trigger: After completing ANY of these milestones:

• Service deployment
• Phase completion
• Major infrastructure change
• Architecture decision

Update Command:

bash automation/update-sandbox-briefing.sh
git add docs/SANDBOX-BRIEFING.md project-files/SANDBOX-BRIEFING.md
git commit -m "Update sandbox briefing: [what changed]"
git push

Gemini Access: https://raw.githubusercontent.com/frostystyle/firefrost-operations-manual/master/project-files/SANDBOX-BRIEFING.md

Workflow:

1. Production work happens with Claude
2. Auto-update sandbox briefing after milestones
3. Gemini always has current context for brainstorming
4. Ideas validated in sandbox → implemented in production