Backstage

Backstage Skill

Nickname: backstage:

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

🔴 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"

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]"]
    
    %% 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

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

When to Use

Trigger patterns:

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

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)

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