backstage companion

Anti-drift protocol script. Ensures parity between docs and system. Triggers: 'bom dia PROJECT' / 'good morning PROJECT' (load project context with health checks)

Backstage Skill

Nickname: backstage:

Objective: Universal project status management for AI-assisted development. Ensures documentation matches reality before every commit.

---

⚠️ Security Notice

This is an admin tool with elevated privileges:

• Executes checks from global path ($HOME/Documents/backstage/backstage/checks/global/)
• Pulls remote code from GitHub (https://github.com/nonlinear/backstage)
• Modifies project files (README, ROADMAP, CHANGELOG with mermaid diagrams)
• Rsyncs updates when using update backstage trigger

Intended for:

• Personal use (you control the upstream repo)
• Trusted teams (shared backstage protocol repo)

Not recommended for:

• Untrusted third-party projects
• Public/open-source projects with unknown contributors

Mitigations in place:

• User confirmation before applying updates
• Git history (all changes committed, revertable)
• Symlink detection (admin mode auto-updates)

Use at your own risk. Review update-backstage.sh and checks.sh before running.

---

🔴 Why This Skill Exists (Anti-Drift)

Backstage-skill = ANTI-DRIFT:

• ✅ Force context awareness (project/epic)
• ✅ Health checks prevent chaos
• ✅ Architecture-first workflow
• ✅ Roadmap visibility = no surprises

WITHOUT IT:
Work happens outside backstage → drift → broken trust → triple metabolic cost

WITH IT:
"good morning X" → automatic context load → work inside boundaries → paridade maintained

---

The Metabolic Cost Problem:

Without backstage, delegation costs triple:

1. The work itself
2. Explicating methodology (ethics, preferences, protocols)
3. Defining WHERE that learning gets stored (VISION? SOUL? SKILL? memory?)

This is exhausting for the human.

Investment is worth it ONLY IF plateau is reached:

• Human teaches ONCE → AI internalizes
• Each session: READ context files → act according to ethics
• Each session: LESS explanation needed
• Plateau = Human delegates, AI executes without supervision

This skill enforces stabilization.
Force context awareness (project/epic/design architecture) to prevent drift.
3x work becomes 1x work.

---

Policies & Checks Enforcement

Backstage-skill enforces ALL rules in checks/ (deterministic + interpretive, global + local).

Enforcement Model

Rendering diagram...

Two enforcement domains:

1. Checks (Interpretive)

   • checks/global/*.md = Universal workflow rules
   • checks/local/*.md = Project-specific overrides
   • Enforced by: AI (reads markdown, interprets context, acts)
   • Always pass: AI reads, understands, will act accordingly

2. Checks (Deterministic)

   • checks/global/*.sh = Universal validation tests
   • checks/local/*.sh = Project-specific tests
   • Enforced by: Bash (executes shell scripts, exit codes)
   • Pass or fail: ✅ (exit 0) or ❌ (exit non-zero)

Polycentric governance:

• Global + local rules coexist
• Local wins on conflict
• AI merges when compatible

Report format:

text

📋 Interpretive checks:
  ✅ checks/global/branch-workflow.md (read)
  ✅ checks/global/commit-style.md (read)
  ✅ checks/local/dogfooding.md (read)

🔍 Checks (deterministic):
  ✅ checks/global/navigation-block-readme.sh
  ✅ checks/global/semver-changelog.sh
  ❌ checks/local/pre-merge-tasks.sh (incomplete tasks)

Self-contained: All prompts in SKILL.md (no external prompt files needed).

---

Mermaid Diagram Generation (Interpretive)

Purpose: Automatically generate + propagate ROADMAP diagram to all backstage files.

Workflow:

1. Parse ROADMAP.md (deterministic - SH):

   bash

   parse-roadmap.sh backstage/ROADMAP.md
   # Output: version|status_emoji|name
   

2. Read checks/ diagram rules (interpretive - AI):

   • checks/global/navigation-block.md defines default format (linear graph, all epics, sequential)
   • checks/local/*.md can override (gantt, flowchart, or diagram: none)
   • Local wins on conflict

3. Generate mermaid (interpretive - AI):

   • Apply checks/ rules to parsed data
   • Create mermaid syntax matching specification
   • Example (default):
     Rendering diagram...

4. Propagate to all files (deterministic - SH):

   • Insert after > 🤖 marker
   • README.md, ROADMAP.md, CHANGELOG.md
   • Remove old diagrams (anti-drift)

AI Prompt (when running backstage-start/end):

Read checks/global/navigation-block.md and checks/local/*.md for diagram rules. Run parse-roadmap.sh to extract epics. Generate mermaid diagram following checks/ rules (prefer local over global). Insert diagram after navigation block (> 🤖) in all backstage files. If local checks say diagram: none, skip generation.

Tools:

• parse-roadmap.sh - Extract version|status|name from ROADMAP.md
• checks/ - Diagram format rules (type, include/exclude logic, status mapping)

---

Polycentric Governance (How It Works)

Rendering diagram...

This skill enforces polycentric governance:

• Reads ALL checks/**/*.md files (global + local)
• Executes ALL checks/**/*.sh files (global + local)
• Merges checks when compatible
• Prefers local checks on conflict
• Reports deterministic check results (pass/fail)

Triggered by: "good morning", "good night", "backstage start/end", "update backstage"

---

Workflow Diagram

Rendering diagram...

Domain labels:

• [MD] - Markdown file (checks/*.md, ROADMAP.md) = Human/AI prompts
• [SH] - Shell script (checks/*.sh, backstage-start.sh) = Machine executables
• [AI reads MD] - AI parses markdown, understands rules/prompts
• [AI writes MD] - AI generates markdown content
• [SH writes MD] - Script modifies markdown files (checkboxes, navigation blocks)
• [Bash runs SH] - Bash executes shell scripts (deterministic validation)
• [AI interprets MD] - AI reads checks/, acts contextually

Critical separation:

• checks/ = prompts - AI reads, interprets, acts
• checks/ = executors - Bash runs commands, returns exit codes
• AI intermediates - Reads checks/, executes checks/, integrates report

Notes:

1️⃣ Trigger: "backstage start", "vamos trabalhar no X", "whatsup" (start mode) OR "backstage end", "boa noite", "wrap up" (end mode)

• Code: backstage-start.sh OR backstage-end.sh

2️⃣ Read README 🤖 block: Find navigation block between > 🤖 markers. Extract all status file paths (ROADMAP, CHANGELOG, checks/, checks/). This is ONLY source of truth for file locations.

• Code: backstage-start.sh::read_navigation_block()

3️⃣ Locate status files: Use paths from 🤖 block. If missing, STOP and ask user where to create them. Check BOTH global (backstage/checks/global/, backstage/checks/global/) and local (backstage/checks/local/, backstage/checks/local/) for polycentric governance.

• Code: backstage-start.sh::locate_status_files()

4️⃣ Check git branch: Run git branch --show-current. Determine work context.

• Code: backstage-start.sh::check_branch()

5️⃣ Analyze changes:

bash

git diff --name-status
git diff --stat
LAST_VERSION=$(grep -m1 "^## v" CHANGELOG.md | cut -d' ' -f2)
git log --oneline "${LAST_VERSION}..HEAD"

Categorize: patch/minor/major. Compare with ROADMAP. Match reality to plans.

• Code: backstage-start.sh::analyze_changes()

6️⃣ Report - Policies + Checks:

Report format:

text

📋 Interpretive checks:
  ✅ checks/global/branch-workflow.md (read)
  ✅ checks/global/commit-style.md (read)
  ✅ checks/local/dogfooding.md (read)

🔍 Checks (deterministic):
  ✅ checks/global/navigation-block-readme.sh
  ✅ checks/global/semver-changelog.sh
  ❌ checks/local/pre-merge-tasks.sh (incomplete tasks)

Policies always ✅: AI reads, interprets, will act accordingly

Checks can fail ❌: Exit code determines status

Mode behavior:

• Start mode: Hard fail (block commit if checks fail)

• End mode: Soft fail (warn, add to ROADMAP)

• Code: backstage-start.sh::report_enforcement()

7️⃣ Update docs: If checks pass, auto-update ROADMAP (mark checkboxes) and CHANGELOG (add new entries at TOP, append-only). Bump version. Add navigation menu to all status files.

• Code: backstage-start.sh::update_docs()

8️⃣ Developer context: Generate outcome-based summary (5 possible states: 🛑 Failed, ⚠️ Mismatch, 🧑 Grooming, ✅ Progress, 🎉 Complete). Show: When, What, Why, Status, Next.

• Code: backstage-start.sh::show_developer_context()

9️⃣ Push / Groom: If checks passed, commit with appropriate message (progress/release). If grooming mode, just update ROADMAP priorities.

• Code: backstage-start.sh::prompt_push()

Victory lap 🏆: Brief reminder of achievements (3 main items max + stats). Keep it short.

• Code: backstage-end.sh::victory_lap()

Body check ⏸️: Ask: Hungry? Thirsty? Tired? Need to stretch? What does body NEED right now?

• Code: backstage-end.sh::body_check()

Close VS Code 🌙: Run countdown + osascript -e 'quit app "Visual Studio Code"'. CRITICAL: Agent must NOT send ANY message after this or VS Code will prompt "unsaved changes".

• Code: backstage-end.sh::close_vscode()

[STAY SILENT]: No reply after closing VS Code (prevents unsaved prompt).

🔄 Update Backstage: "update backstage" trigger

• Find backstage folder: Search CWD for */backstage/ directory
• Check if symlinked: If checks/global/ is symlink → already auto-updates (skip)
• Fetch upstream: Clone https://github.com/nonlinear/backstage (temp dir)
• Compare: Diff local checks/global/ vs upstream
• Generate changelog: Show NEW, CHANGED, REMOVED files (with descriptions)
• Prompt user: "Apply updates? (y/n)"
• Apply if yes: rsync --delete upstream → local
• Report: What changed, how many files
• Code: update-backstage.sh

---

When to Use

Trigger patterns:

"Bom dia" / "Good morning" + PROJECT:

• bom dia personal / good morning personal
• bom dia librarian / good morning librarian
• Action: Load project context + run health checks
• Output: Current epic, roadmap status, branch info, gaps

"Update backstage":

• Action: Compare local */backstage/checks/global/ against official repo
• Detect changes: What's NEW or CHANGED in upstream
• Show delta: Mini changelog (1 paragraph: what you GAIN if updated)
• Confirm: User approves update
• Execute: Pull latest checks/global/ files from upstream
• Output: Updated files list, what changed

Start mode:

• "backstage start"
• "whatsup"
• "vamos trabalhar no X"
• "what's the status"
• Before every commit (especially after long breaks)

End mode:

• "backstage end"
• "boa noite"
• "wrap up"
• "pause work"
• End of work session, when tired, or context-switch

---

"Update Backstage" Workflow

Trigger: update backstage (from any project using backstage protocol)

Purpose: Sync local checks/global/ with latest from upstream repo, show what's new.

How It Works

1. Detect project backstage folder:

   bash

   # Search up from CWD for backstage/ folder
   find . -type d -name "backstage" | grep -E "backstage$"
   # Or read README 🤖 block for backstage location
   

2. Confirm upstream source:

   bash

   # Check if checks/global/ is symlink (admin mode)
   if [ -L "backstage/checks/global" ]; then
     echo "✅ Symlinked to upstream (auto-updates)"
     exit 0
   fi
   
   # Otherwise, assume official repo
   UPSTREAM="https://github.com/nonlinear/backstage"
   echo "Upstream: $UPSTREAM"
   echo "Confirm this is correct? (y/n)"
   

3. Fetch latest from upstream:

   bash

   # Clone or pull latest
   TMP_DIR=$(mktemp -d)
   git clone --depth 1 "$UPSTREAM" "$TMP_DIR/backstage"
   

4. Compare local vs upstream:

   bash

   # Diff local checks/global/ vs upstream
   diff -qr backstage/checks/global/ "$TMP_DIR/backstage/backstage/checks/global/"
   

5. Generate mini changelog:

   text

   📦 Backstage Updates Available:
   
   NEW files (3):
   - skill-publish-warning.sh (warns before merging unpublished skills)
   - rebase-cadence.md (suggests rebase if branch >7 days old)
   - epic-notes-orphan-detection.md (detects orphan epic notes)
   
   CHANGED files (2):
   - merge-to-main.md (added Step 0: skill publish check)
   - epic-branch.sh (improved detection logic)
   
   WHAT YOU GAIN:
   Better skill publishing workflow, orphan detection, rebase reminders.
   

6. Prompt user:

   text

   Apply these updates? (y/n)
   

7. Update if confirmed:

   bash

   # Copy upstream checks/global/ to local
   rsync -av --delete "$TMP_DIR/backstage/backstage/checks/global/" backstage/checks/global/
   
   # Cleanup
   rm -rf "$TMP_DIR"
   
   echo "✅ Updated checks/global/ from upstream"
   

8. Report:

   text

   🎉 Backstage updated!
   
   Files changed: 5
   - Added: skill-publish-warning.sh, rebase-cadence.md, epic-notes-orphan-detection.md
   - Modified: merge-to-main.md, epic-branch.sh
   
   Next: Run 'backstage start' to test new checks.
   

Edge Cases

Symlinked (admin mode):

• If checks/global/ is symlink → already auto-updates
• Just report: "✅ Already symlinked to upstream (no action needed)"

No changes:

• If local == upstream → report: "✅ Already up to date"

Conflicts:

• If user modified global checks locally → warn, ask to resolve
• Suggest: copy to checks/local/ (overrides) before updating

No internet:

• If git clone fails → report: "❌ Can't reach upstream (offline?)"

---

Key Principles

1. README's 🤖 block = Single source of truth for file locations
2. Status files = AI prompts (checks/ = tests, checks/ = rules, ROADMAP = backlog, CHANGELOG = history)
3. Polycentric governance (global + local rules, local wins on conflict)
4. Checks must pass before commit (non-negotiable for start mode, soft fail for end mode)
5. CHANGELOG is append-only (never edit old entries, add NEW entry for corrections)
6. 5 possible outcomes (Failed, Mismatch, Grooming, Progress, Complete)
7. Documentation auto-syncs with reality (mark checkboxes, bump versions, move epics)
8. Body check at end (mental health + momentum preservation)
9. Silent after VS Code close (prevent unsaved prompt)
10. Works on ANY project (no hardcoded paths, reads README first)

---

The 5 States (Start Mode)

State	When	Action	Can Push?
🛑 Failed Checks	Tests fail	Fix issues	❌ NO
⚠️ Docs Mismatch	Code ≠ docs	Auto-update docs	✅ YES
🧑 Grooming	No changes	Plan next work	N/A
✅ In Progress	Partial work	Update checkboxes	✅ YES
🎉 Version Complete	All done!	Move to CHANGELOG	✅ YES 🎉

---

Check Policy

From checks/:

• Epic branches: Soft fail (warn but allow)
• Main branch: Hard fail (block merge)
• Wrap-up (end mode): Soft fail (list fixes, don't push)

---

The 3-Level System

Level 1: Personal (not tracked)

• Your books, notes, local config
• Not part of any project

Level 2: Project-Specific (e.g., Librarian MCP)

• Generic tool others can use
• Has status files (ROADMAP, CHANGELOG, checks/, checks/)
• Example flagship project for Level 3

Level 3: Meta-Workflow (this skill)

• Works for ANY project
• No hardcoded paths
• Reads README to find everything
• Can be copied anywhere

---

Reference Prompts

Original prompts (for future refinement):

• backstage-start.prompt.md - Full start workflow specification
• backstage-close.prompt.md - Full end workflow specification

Location: /Users/nfrota/Documents/nonlinear/.github/prompts/

Note: This SKILL.md is a DRAFT distillation of those prompts. Future refinements will improve diagram, add emoji notes, clarify steps. The original prompts contain ALL details.

---

TODO / Future Refinements

• Update .sh scripts to read checks/ and checks/ folders
• Add emoji notes (like design-discrepancy 1️⃣-8️⃣ format)
• Simplify diagram (consolidated enforcement, removed "separate" step)
• Add code execution points (where scripts run, if any)
• Create templates (for new projects without status files)
• Document edge cases (no git, no README, corrupted files)
• Add examples (successful runs, failed runs, grooming sessions)
• Test on multiple projects (validate universal workflow)
• Consider splitting (start vs end as separate skills?)

---

Created: 2026-02-12 Updated: 2026-02-18 (v1.0.0 - modular checks/checks) Status: Documentation updated, scripts pending Location: ~/Documents/backstage/skills/backstage/SKILL.md