Skill: nonlinear/backstage (version 1.0.4)

--- 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: - https://github.com/nonlinear/backstage 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 ```mermaid 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): ```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): ```mermaid 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) ```mermaid 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 ```mermaid 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:** ```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:** ``` 📋 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:** ``` 📦 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:** ```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:** ``` 🎉 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`


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: suspicious (CRITICAL)