LeoYeAI/openclaw-master-skills/backstage

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

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

Parse ROADMAP.md (deterministic - SH):

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

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
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]
```
Propagate to all files (deterministic - SH):
- Insert after > 🤖 marker
- README.md, ROADMAP.md, CHANGELOG.md
- Remove old diagrams (anti-drift)

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

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

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

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

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

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

Fetch latest from upstream:

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

Compare local vs upstream:

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

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.

Prompt user:
```
Apply these updates? (y/n)
```

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"

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.

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 🎉

backstage

Summary

SKILL.md

Backstage Skill

⚠️ Security Notice

🔴 Why This Skill Exists (Anti-Drift)

Policies & Checks Enforcement

Enforcement Model

Mermaid Diagram Generation (Interpretive)

Polycentric Governance (How It Works)

Workflow Diagram

When to Use

"Update Backstage" Workflow

How It Works

Edge Cases

Key Principles

The 5 States (Start Mode)

Check Policy

The 3-Level System

Reference Prompts

TODO / Future Refinements

Related skills