feat: Add comprehensive fallback mechanism and version tracking (#6)

ukjaiswal · Uttam Jaiswal · web-flow · commit d6362e6b0650 · 2026-02-22T08:52:08.000+05:30
- Add fallback guidance for MCP server unavailability - Add published versions tracking (PyPI/MCP Registry → git tags) - Enhance CLAUDE-template.md with 7 practice summaries - Add cross-references between README, MIGRATION-GUIDE, CLAUDE-template - Add troubleshooting section for MCP server failures Fallback options: - GitHub practices (primary) - Local clone access (offline) - CLAUDE.md appendix (emergency) Version tracking: - Link PyPI/MCP Registry v1.4.0 to git tag v1.4.0 (34ca572) - Show latest development vs published versions Co-authored-by: Uttam Jaiswal <uttam.jaiswal@skill-mine.com>
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [1.4.0] - 2026-02-20
 
+**Git Tag:** [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) | **Commit:** `34ca572`
+**Published:** PyPI ✅ (2026-02-19) | MCP Registry ✅ (2026-02-20)
+
 ### Fixed
 
 **Critical MCP Server Stability Issue:**
diff --git a/MIGRATION-GUIDE.md b/MIGRATION-GUIDE.md
@@ -281,6 +281,11 @@ This project follows standard DevOps practices provided by the **DevOps Practice
 
 **Quick reference:** See [PRACTICE-INDEX.md](../devops-practices-mcp/PRACTICE-INDEX.md) for scenario-based lookup.
 
+**⚠️ Fallback if MCP unavailable:**
+- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices
+- Local: `~/.mcp-servers/devops-practices-mcp/practices/`
+- Critical summaries in Appendix below
+
 ### Templates Available
 
 1. **CLAUDE.md** - Project instructions template
@@ -289,6 +294,27 @@ This project follows standard DevOps practices provided by the **DevOps Practice
 4. **RUNBOOK.md** - Session log template (use for EVERY session)
 ```
 
+### 4.3: Add Fallback Appendix (Recommended)
+
+**For resilience, add critical practice summaries as fallback:**
+
+Use the appendix from [CLAUDE-template.md](templates/CLAUDE-template.md) or create a minimal one:
+
+```markdown
+## Appendix: Critical Practices (Fallback if MCP Unavailable)
+
+**Full practices**: https://github.com/ai-4-devops/devops-practices/tree/main/practices
+
+### Essential Patterns
+- **Air-gapped**: Laptop → S3 → Bastion (no direct AWS from laptop)
+- **Docs**: guides/ = HOW | RUNBOOKS/ = WHAT | reports/ = WHY
+- **Git**: Always `git mv` for tracked files
+- **Tracking**: Update TRACKER.md + CURRENT-STATE.md every session
+- **Runbooks**: MANDATORY for every session in docs/RUNBOOKS/
+
+See template for full appendix with summaries.
+```
+
 ---
 
 ## Step 5: Test MCP Integration
@@ -500,6 +526,14 @@ git push origin main
 4. Restart Claude completely
 5. Check Claude logs for MCP errors
 
+**Fallback workaround:**
+```
+If MCP server won't start, access practices directly:
+- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices
+- Local: cat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md
+- Appendix in project CLAUDE.md (if you added it in Step 4.3)
+```
+
 ### Issue: Practice content is outdated
 
 **Symptoms:** MCP returns old version of practice
diff --git a/README.md b/README.md
@@ -16,6 +16,11 @@ mcp-name: io.github.ai-4-devops/devops-practices
 
 **Status**: 🎉 **Officially Published** in the [MCP Registry](https://registry.modelcontextprotocol.io/?search=devops-practices) (Published: February 18, 2026)
 
+**Published Versions:**
+- 📦 **PyPI**: [v1.4.0](https://pypi.org/project/devops-practices-mcp/1.4.0/) → Git tag [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) (`34ca572`)
+- 🌐 **MCP Registry**: v1.4.0 → Git tag [v1.4.0](https://github.com/ai-4-devops/devops-practices/releases/tag/v1.4.0) (`34ca572`)
+- 🚀 **Latest Development**: [main branch](https://github.com/ai-4-devops/devops-practices) (may include unreleased features)
+
 ---
 
 > **Who is this for?** DevOps engineers using **Claude Code (VS Code plugin)** for PoC development.
@@ -81,6 +86,7 @@ When searching "devops" in the MCP Registry (as of February 2026), this is the o
 - ✅ **Background**: Runs silently while you work
 - ✅ **On-demand**: Claude queries practices as needed
 - ✅ **Auto-stop**: Shuts down when Claude closes
+- ✅ **Fallback**: Access practices via GitHub/local if MCP unavailable (see [Troubleshooting](#mcp-server-is-down-or-unavailable))
 
 **Configuration Options:**
 
@@ -329,15 +335,23 @@ Claude has access to shared DevOps practices via MCP:
 - Git best practices
 - Efficiency guidelines
 
+⚠️ Fallback: If MCP unavailable, see Appendix or GitHub practices
+
 ## Project-Specific: [Project Details]
 [Only project-specific instructions here]
+
+## Appendix: Critical Practices (Fallback)
+[Emergency practice summaries if MCP down - see CLAUDE-template.md]
 ```
 
 ### Benefits
 - **DRY**: Shared practices written once, used everywhere
 - **Consistency**: All projects follow same standards
 - **Maintainability**: Update once, all projects benefit
 - **Discoverability**: Claude can query practices when needed
+- **Resilient**: Fallback to GitHub/local/appendix if MCP unavailable
+
+**Template:** See [CLAUDE-template.md](templates/CLAUDE-template.md) for full structure including fallback appendix
 
 ---
 
@@ -769,6 +783,45 @@ git checkout -b hotfix/critical-bug
 
 **Log location:** `~/.cache/claude/mcp-devops-practices.log`
 
+### MCP Server is Down or Unavailable
+
+**Symptoms:** MCP server process crashed, not responding, or cannot start
+
+**Fallback Options:**
+
+**Option 1: GitHub Practices (Recommended)**
+```
+Access practices directly from GitHub:
+https://github.com/ai-4-devops/devops-practices/tree/main/practices
+
+Ask Claude to read practices via GitHub URLs when MCP unavailable.
+```
+
+**Option 2: Local Clone**
+```bash
+# Access practices from local clone
+ls ~/.mcp-servers/devops-practices-mcp/practices/
+
+# Read practice directly
+cat ~/.mcp-servers/devops-practices-mcp/practices/03-02-air-gapped-workflow.md
+```
+
+**Option 3: CLAUDE.md Appendix**
+```
+Projects using the CLAUDE-template.md have a built-in appendix
+with critical practice summaries for emergency fallback.
+
+See: templates/CLAUDE-template.md (Appendix section)
+```
+
+**Prevention:**
+- Use [.mcp.json](.mcp.json) for project-level config (more reliable)
+- Add MCP health check to pre-session checklist
+- Keep local clone updated: `git pull origin main`
+- Monitor logs: `tail -f ~/.cache/claude/mcp-devops-practices.log`
+
+**Related:** [MIGRATION-GUIDE.md](MIGRATION-GUIDE.md#troubleshooting) for project-specific fallback setup
+
 ### Practice File Not Found
 1. Verify file exists: `ls practices/`
 2. Check filename matches exactly (case-sensitive)
diff --git a/templates/CLAUDE-template.md b/templates/CLAUDE-template.md
@@ -12,7 +12,7 @@ Claude has access to shared DevOps practices via MCP service. Query practices wh
 - **Git practices** - Using `git mv`, commit conventions, backup protocols
 - **Efficiency guidelines** - When to script vs copy-paste, command batching
 
-**⚠️ Fallback**: If MCP unavailable, critical practices are duplicated below in Appendix.
+**⚠️ Fallback**: If MCP unavailable, critical practices are in Appendix below + [GitHub practices](https://github.com/ai-4-devops/devops-practices/tree/main/practices)
 
 ---
 
@@ -63,23 +63,110 @@ You are my **expert ${ROLE}**. You bring deep expertise in ${EXPERTISE_AREAS}.
 
 ## Appendix: Critical Practices (Fallback if MCP Unavailable)
 
-### Air-Gapped Workflow (Summary)
+**📚 Full Practices**: If MCP server is down, access complete practices at:
+- GitHub: https://github.com/ai-4-devops/devops-practices/tree/main/practices
+- Local clone: `~/.mcp-servers/devops-practices-mcp/practices/`
+
+**Below are essential summaries for quick reference:**
+
+---
+
+### 03-02 Air-Gapped Workflow (Summary)
+**File**: [03-02-air-gapped-workflow.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/03-02-air-gapped-workflow.md)
+
+**Environment Separation:**
 - **Laptop**: Git repo, Claude - NO AWS access
 - **CloudShell/VPS**: ECR uploads - Uses environment variables
 - **Bastion**: EKS access via SSM - Copy/paste commands only
 - **EKS**: Air-gapped - Images must be in ECR
 
-**File Transfer**: Laptop → S3 → Bastion
+**File Transfer Pattern**: Laptop → S3 → Bastion
+**Command Flow**: Write on Laptop → Execute on Bastion (copy/paste)
+
+---
+
+### 04-01 Documentation Standards (Summary)
+**File**: [04-01-documentation-standards.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/04-01-documentation-standards.md)
+
+**Directory Structure:**
+- `docs/guides/` = HOW to deploy (procedures)
+- `docs/RUNBOOKS/` = WHAT we did (session logs - MANDATORY)
+- `docs/reports/` = WHY we did it (decisions)
 
-### Documentation Structure (Summary)
-- `docs/guides/` = HOW to deploy
-- `docs/RUNBOOKS/` = WHAT we did
-- `docs/reports/` = WHY we did it
+**Naming**: `YYYYMMDD-descriptive-name.md`
 
-### Git Practices (Summary)
+---
+
+### 02-01 Git Practices (Summary)
+**File**: [02-01-git-practices.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/02-01-git-practices.md)
+
+**Critical Rules:**
 - ALWAYS use `git mv` for tracked files (preserves history)
 - NEVER commit without explicit user request
 - Backup before changes: `backup-$(date -u +%Y%m%dT%H%M%SZ).yaml`
+- Follow GitLab Flow: feature → develop → main
+
+---
+
+### 01-02 Task Tracking (Summary)
+**File**: [01-02-task-tracking.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/01-02-task-tracking.md)
+
+**Required Files:**
+- `TRACKER.md` - Milestones and tasks
+- `CURRENT-STATE.md` - Session handoff state
+- Update both at end of every session
+
+**Template**: [TRACKER-template.md](https://github.com/ai-4-devops/devops-practices/blob/main/templates/TRACKER-template.md)
+
+---
+
+### 04-03 Runbook Documentation (Summary)
+**File**: [04-03-runbook-documentation.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/04-03-runbook-documentation.md)
+
+**MANDATORY**: Create runbook for EVERY session
+**Location**: `docs/RUNBOOKS/YYYYMMDD-session-N-title.md`
+**Template**: [RUNBOOK-template.md](https://github.com/ai-4-devops/devops-practices/blob/main/templates/RUNBOOK-template.md)
+
+**Required Sections**: Objective, Pre-work, Execution, Observations, Next Steps
+
+---
+
+### 03-01 Configuration Management (Summary)
+**File**: [03-01-configuration-management.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/03-01-configuration-management.md)
+
+**Structure:**
+```
+configs/${ENV}/${COMPONENT}/
+  ├── config-template.yaml  # Placeholder version
+  ├── config.yaml          # Actual values (gitignored)
+  └── README.md            # Parameter documentation
+```
+
+**Rule**: NEVER commit actual credentials or endpoints to git
+
+---
+
+### 01-01 Session Continuity (Summary)
+**File**: [01-01-session-continuity.md](https://github.com/ai-4-devops/devops-practices/blob/main/practices/01-01-session-continuity.md)
+
+**End of Session:**
+1. Update `CURRENT-STATE.md` with current status
+2. Update `TRACKER.md` with progress
+3. Create/update runbook in `docs/RUNBOOKS/`
+4. Commit all changes
+
+**Start of Session:**
+1. Read `CURRENT-STATE.md`
+2. Review `TRACKER.md`
+3. Read last runbook
+
+---
+
+**💡 MCP Server Troubleshooting**:
+- Verify MCP running: `ps aux | grep mcp-server`
+- Check logs: `~/.cache/claude/mcp-devops-practices.log`
+- Restart Claude Code/Desktop to reload MCP
+- Health check: `~/.mcp-servers/devops-practices-mcp/health-check.sh`
 
 ---
 
