backstage

star 8

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

modbender By modbender schedule Updated 3/6/2026
play_arrow Run Skill in Manus View GitHub

name: backstage

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

type: public

version: 1.0.2

status: production

author: nonlinear

license: MIT

requires:

dependencies:

  • bash

  • awk

  • sed

  • git

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


flowchart TD

    READ_CHK["Read checks/<br/>global + local<br/>[Deterministic .sh + Interpretive .md]"]

    

    CONFLICT{Conflict?}

    MERGE[Merge compatible rules]

    LOCAL[Local wins]

    

    AI["AI interprets .md checks<br/>[Contextual enforcement]"]

    SH["Bash executes .sh checks<br/>[Deterministic validation]"]

    

    AI_ACT[✅ Enforce or discuss]

    AI_AMBIG[⚠️ Ask user]

    

    SH_OK[✅ All checks pass]

    SH_FAIL[❌ Checks failed]

    

    REPORT["Report:<br/>📋 Interpretive (always ✅)<br/>🔍 Deterministic (✅/❌)"]

    

    READ_CHK --> CONFLICT

    CONFLICT -->|No| MERGE

    CONFLICT -->|Yes| LOCAL

    MERGE --> AI

    MERGE --> SH

    LOCAL --> AI

    LOCAL --> SH

    

    AI -->|Clear| AI_ACT

    AI -->|Ambiguous| AI_AMBIG

    

    SH -->|Pass| SH_OK

    SH -->|Fail| SH_FAIL

    

    AI_ACT --> REPORT

    AI_AMBIG --> REPORT

    SH_OK --> REPORT

    SH_FAIL --> REPORT

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:


📋 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):

    
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):

      
graph LR

    A[🏗️ v0.1.0 Active Epic] --> B[📋 v0.2.0 Backlog Epic]

  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)


flowchart TD

    GLOBAL_POL[checks/global/*.md<br/>Universal rules]

    LOCAL_POL[checks/local/*.md<br/>Project-specific overrides]

    

    GLOBAL_CHK[checks/global/*.sh<br/>Universal tests]

    LOCAL_CHK[checks/local/*.sh<br/>Project-specific tests]

    

    AI[AI reads checks/]

    BASH[Bash executes checks/]

    CONFLICT{Conflict?}

    

    GLOBAL_POL --> AI

    LOCAL_POL --> AI

    GLOBAL_CHK --> BASH

    LOCAL_CHK --> BASH

    

    AI --> CONFLICT

    CONFLICT -->|Yes| LOCAL_POL

    CONFLICT -->|No| MERGE[Merge rules]

    

    MERGE --> ACTION[Execute workflow]

    LOCAL_POL --> ACTION

    BASH --> ACTION

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


flowchart TD

    START["Trigger 1️⃣<br/>[SH]"]

    MODE{"Session mode?"}

    

    %% Common enforcement module

    READ_POL["Read checks/<br/>global + local<br/>[AI interprets MD]"]

    EXEC_CHK["Execute checks/<br/>global + local<br/>[Bash runs SH]"]

    

    REPORT["Report 6️⃣<br/>📋 Interpretive (✅)<br/>🔍 Checks (✅/❌)"]

    CHECKS_GATE{"All checks<br/>passed?"}

    

    %% Start Branch

    START_BRANCH["Read README 🤖 block 2️⃣<br/>[MD → AI]"]

    START_FILES["Locate status files 3️⃣<br/>[SH]"]

    START_GIT["Check git branch 4️⃣<br/>[SH]"]

    START_WORK["Analyze changes 5️⃣<br/>[SH]"]

    START_FIX["🛑 STOP: Fix issues<br/>[AI + SH]"]

    START_UPDATE["Update docs 7️⃣<br/>[SH writes MD]"]

    START_REPORT["Developer context 8️⃣<br/>[AI reads MD]"]

    START_PUSH["Push / Groom 9️⃣<br/>[SH]"]

    

    %% End Branch

    END_FIXES["Add fixes to roadmap<br/>[AI writes MD]"]

    END_PUSH["Commit + push<br/>[SH]"]

    END_VICTORY["Victory lap 🏆<br/>[AI reads MD]"]

    END_BODY["Body check ⏸️<br/>[AI prompt]"]

    END_CLOSE["Close VS Code 🌙<br/>[SH]"]

    END_SILENT["[STAY SILENT]"]

    

    %% Update Backstage Branch

    UPDATE_DETECT["Find backstage/ folder<br/>[SH]"]

    UPDATE_CHECK_SYM{"Symlinked?"}

    UPDATE_SKIP["✅ Already auto-updates<br/>[Report]"]

    UPDATE_FETCH["Fetch upstream<br/>[SH: git clone]"]

    UPDATE_DIFF["Compare local vs upstream<br/>[SH: diff]"]

    UPDATE_UPTODATE{"Changes<br/>found?"}

    UPDATE_UPTODATE_SKIP["✅ Already up to date<br/>[Report]"]

    UPDATE_CHANGELOG["Generate mini changelog<br/>[AI reads diffs]"]

    UPDATE_PROMPT{"User<br/>approves?"}

    UPDATE_ABORT["Aborted<br/>[Report]"]

    UPDATE_APPLY["rsync upstream → local<br/>[SH]"]

    UPDATE_REPORT["🎉 Updated!<br/>[Report changes]"]

    

    %% Flow

    START --> MODE

    

    MODE -->|Start| START_BRANCH

    START_BRANCH --> START_FILES

    START_FILES --> START_GIT

    START_GIT --> START_WORK

    START_WORK --> READ_POL

    START_WORK --> EXEC_CHK

    

    READ_POL --> REPORT

    EXEC_CHK --> REPORT

    REPORT --> CHECKS_GATE

    

    CHECKS_GATE -->|No, start mode| START_FIX

    START_FIX --> READ_POL

    CHECKS_GATE -->|Yes| START_UPDATE

    START_UPDATE --> START_REPORT

    START_REPORT --> START_PUSH

    

    MODE -->|End| READ_POL

    MODE -->|End| EXEC_CHK

    CHECKS_GATE -->|No, end mode| END_FIXES

    CHECKS_GATE -->|Yes| END_PUSH

    END_FIXES --> END_VICTORY

    END_PUSH --> END_VICTORY

    END_VICTORY --> END_BODY

    END_BODY --> END_CLOSE

    END_CLOSE --> END_SILENT

    

    MODE -->|Update| UPDATE_DETECT

    UPDATE_DETECT --> UPDATE_CHECK_SYM

    UPDATE_CHECK_SYM -->|Yes| UPDATE_SKIP

    UPDATE_CHECK_SYM -->|No| UPDATE_FETCH

    UPDATE_FETCH --> UPDATE_DIFF

    UPDATE_DIFF --> UPDATE_UPTODATE

    UPDATE_UPTODATE -->|No| UPDATE_UPTODATE_SKIP

    UPDATE_UPTODATE -->|Yes| UPDATE_CHANGELOG

    UPDATE_CHANGELOG --> UPDATE_PROMPT

    UPDATE_PROMPT -->|No| UPDATE_ABORT

    UPDATE_PROMPT -->|Yes| UPDATE_APPLY

    UPDATE_APPLY --> UPDATE_REPORT

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: 


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:


📋 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:

    
# 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:

    
# 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:

    
# Clone or pull latest

TMP_DIR=$(mktemp -d)

git clone --depth 1 "$UPSTREAM" "$TMP_DIR/backstage"

  4. Compare local vs upstream:

    
# Diff local checks/global/ vs upstream

diff -qr backstage/checks/global/ "$TMP_DIR/backstage/backstage/checks/global/"

  5. Generate mini changelog:

    
📦 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:

    
Apply these updates? (y/n)

  7. Update if confirmed:

    
# 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:

    
🎉 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

Install via CLI
npx skills add https://github.com/modbender/skill-library-mcp --skill backstage
Repository Details
star Stars 8
call_split Forks 2
navigation Branch main
article Path SKILL.md
More from Creator
modbender
modbender Explore all skills →