create-egregore 0.20.2 → 0.21.0-runtime-mvp.1

package/runtime/claude/.claude/skills/commit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: commit
+description: "Stage changes and create a commit with a properly formatted message. Use for /commit, or saving work locally — not sharing it (/push) or opening a pull request (/pr)."
+---
+
+Stage changes and commit with a message.
+
+## When to invoke
+
+User says: "/commit", "commit this", "stage and commit", "save this change locally"
+Not this: sharing your commit with others → `/push` · opening a pull request → `/pr`
+
+Message (optional): $ARGUMENTS
+
+## Execution boundary
+
+This is a deterministic Git operation. Run it inline through the shared Git
+mechanics; do not spend a Loom/model-routing call or delegate it to another
+agent. Judgment is limited to selecting relevant files and composing the
+message.
+
+## Before anything else
+
+Resolve `BASE_BRANCH` through `bin/lib/config.sh` → `_get_base_branch` (pass the managed repo name when applicable). Check `git branch --show-current`. If on a protected branch (`$BASE_BRANCH`, `develop`, `main`, or `master`):
+  → Use the resolved base branch (default `"develop"`)
+  → Create a working branch: `git fetch origin $BASE_BRANCH --quiet && git checkout --no-track -b dev/{author}/{topic-slug} origin/$BASE_BRANCH`
+  → Tell the user: "Creating a working branch for this..." — never mention git commands to the user.
+  → Then proceed with the commit.
+
+## What to do
+
+1. Show modified and untracked files
+2. Stage relevant files (ignore build artifacts)
+3. Compose the message per the convention below — suggest one derived
+   from the diff, or take the user's and align it to the convention
+4. Create the commit
+
+## Message convention
+
+Full spec: `.claude/context/commit-format.md`. Wording:
+`.claude/context/git-language.md`. The short form:
+
+- Subject `type(scope): imperative summary` — ≤ 72 chars (aim ≤ 50),
+  lowercase, no trailing period. Same grammar and type set as PR
+  titles. It completes "if applied, this commit will ___".
+- Body (when the diff cannot explain its own motivation): blank line
+  after the subject, wrapped at 72, what and why — never how.
+- Agent-authored commits end with a trailer block as the final
+  paragraph:
+
+  ```bash
+  SID=$(cat .egregore-session-id 2>/dev/null)
+  git commit -m "feat(mcp): add API key authentication" -m "Egregore-Session: $SID
+  Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>"
+  ```
+
+  Omit the `Egregore-Session` line when the file is absent; use your
+  harness's own identity line. Humans committing by hand skip
+  trailers.
+- One logical change per commit — split when the parts are
+  independently revertable.
+
+## Example
+
+```
+> /commit
+
+Checking changes...
+
+Modified files:
+  src/mcp/auth.py        (+42, -3)
+  src/mcp/server.py      (+8, -2)
+  tests/test_auth.py     (+28, new file)
+
+Untracked:
+  src/mcp/__pycache__/   (ignored ✓)
+
+Staging modified files...
+  git add src/mcp/auth.py src/mcp/server.py tests/test_auth.py
+
+Enter commit message (or I can suggest one):
+> feat(mcp): add API key authentication
+
+  git commit -m "feat(mcp): add API key authentication"  # + trailer block
+  ✓ Committed (abc1234)
+
+Changes committed locally. Run /push to share, or /pr when ready for review.
+```
+
+## With message argument
+
+```
+> /commit docs(readme): fix typo
+
+Staging and committing...
+  git add -A
+  git commit -m "docs(readme): fix typo"
+  ✓ Committed (def5678)
+```
+
+## Next
+
+Run `/push` to share, or keep working and commit again.

package/runtime/claude/.claude/skills/contribute/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: contribute
+description: "Contribute an improvement back to the upstream Egregore framework as a cross-fork pull request. Use for /contribute, or submitting a framework fix upstream — not saving org work (/save) or filing a bug (/issue)."
+---
+
+Contribute an improvement back to the upstream Egregore framework.
+
+Arguments: $ARGUMENTS
+
+## When to invoke
+
+User says: "I want to improve this command", "submit a fix upstream", "contribute back",
+"send this to egregore", "contribute to the framework", "upstream PR", "fix in upstream"
+Not this: saving work to org repo → `/save` · filing a bug → `/issue` · syncing from upstream → `/update`
+
+## Argument routing
+
+Parse `$ARGUMENTS`:
+
+- **Empty** → Interactive mode (ask what they want to improve)
+- `submit` → Submit mode (push changes + create cross-fork PR)
+- `status` → Show current contribution state
+- **Anything else** → Interactive mode with topic pre-seeded from arguments
+
+## Step 0: Gate check
+
+Resolve the contribution target through the shared executable guard. This is
+mandatory for every mode, including `status`, and replaces any hand-written
+interpretation of `upstream_url`:
+
+```bash
+UPSTREAM_REPO=$(bash bin/contribute-guard.sh) || exit $?
+```
+
+If the guard refuses because `upstream_url` is `"none"`, tell the user:
+
+> This is the framework source repository. Use `/save` to push changes to its configured integration branch.
+
+Stop.
+
+For malformed configuration, unsupported URLs, or any other guard failure,
+show its error and stop. Never substitute a public target after a guard error.
+
+## Step 1: Check auth + get username
+
+```bash
+GH_USER=$(gh api user --jq '.login' 2>/dev/null)
+```
+
+If empty: "Run `bash bin/github-auth.sh` first — you need GitHub access to contribute." Stop.
+
+---
+
+## Interactive mode (default / topic provided)
+
+### Step 2: Understand intent
+
+If `$ARGUMENTS` is non-empty (and not `submit`/`status`), use as the topic description.
+
+If empty, use AskUserQuestion:
+
+```
+header: "Contribute"
+question: "What do you want to improve in the Egregore framework?"
+options:
+  - label: "A command"
+    description: "Improve or fix a slash command"
+  - label: "A script"
+    description: "Improve or fix a bin/ script"
+  - label: "CLAUDE.md"
+    description: "Update framework behavior"
+  - label: "Something else"
+    description: "I'll describe what I want to change"
+```
+
+If freeform or "Something else" → ask the user to describe the change.
+
+### Step 3: Set up infrastructure (silent — no output to user)
+
+All three steps in one bash call:
+
+```bash
+# Revalidate immediately before the first external mutation. A target change
+# or source-repository config stops the entire command block.
+bash bin/contribute-guard.sh --expect "$UPSTREAM_REPO" >/dev/null || exit $?
+
+# 3a: Fork upstream (idempotent — no-ops if fork exists)
+gh repo fork "$UPSTREAM_REPO" --clone=false 2>/dev/null || true
+
+# 3b: Add contribute remote (skip if exists)
+if ! git remote get-url contribute &>/dev/null; then
+  REPO_NAME=$(echo "$UPSTREAM_REPO" | cut -d'/' -f2)
+  git remote add contribute "https://github.com/${GH_USER}/${REPO_NAME}.git" 2>/dev/null
+fi
+git fetch contribute --quiet 2>/dev/null || true
+
+# 3c: Create contribution branch from upstream/main
+git fetch upstream main --quiet 2>/dev/null || true
+```
+
+Derive topic slug:
+```bash
+SLUG=$(echo "$DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/--*/-/g; s/^-//; s/-$//' | cut -c1-40)
+CONTRIBUTE_BRANCH="contribute/${SLUG}"
+```
+
+Save current branch for later return:
+```bash
+PREVIOUS_BRANCH=$(git branch --show-current)
+```
+
+Check if branch exists:
+```bash
+if git show-ref --verify --quiet "refs/heads/$CONTRIBUTE_BRANCH" 2>/dev/null; then
+  # Branch exists — ask: resume or start fresh?
+fi
+```
+
+If new:
+```bash
+git checkout -b "$CONTRIBUTE_BRANCH" upstream/main --quiet
+```
+
+### Step 4: Confirm setup
+
+```
+Contributing to {UPSTREAM_REPO}
+
+  Fork:   github.com/{GH_USER}/{repo_name}
+  Branch: {CONTRIBUTE_BRANCH}
+  Scope:  bin/ · .claude/commands/ · .claude/agents/ · loom/ · CLAUDE.md · skills/
+
+Make your changes, then run /contribute submit.
+```
+
+### Step 5: Telemetry
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"contribute","subcommand":"start"}' 2>/dev/null &
+```
+
+The user now works on their changes. Claude assists normally. When ready, they run `/contribute submit`.
+
+---
+
+## Submit mode (`/contribute submit`)
+
+### Step 6: Validate state
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+```
+
+**If not on a `contribute/*` branch**: Check for framework changes vs upstream:
+
+```bash
+FRAMEWORK_CHANGES=$(git diff upstream/main --name-only -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/ 2>/dev/null)
+```
+
+- If changes exist on a non-contribute branch: offer to cherry-pick into a contribution branch
+- If no changes: "No framework changes found. Make changes first, then `/contribute submit`." Stop.
+
+**If on a `contribute/*` branch**: Proceed.
+
+### Step 7: Show changes for review
+
+```bash
+DIFF_STAT=$(git diff upstream/main --stat -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/)
+DIFF_FILES=$(git diff upstream/main --name-only -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/)
+```
+
+Show the diff. Also warn about out-of-scope changes:
+
+```bash
+NON_FRAMEWORK=$(git diff upstream/main --name-only | grep -v '^bin/' | grep -v '^\.claude/commands/' | grep -v '^\.claude/agents/' | grep -v '^loom/' | grep -v '^CLAUDE\.md$' | grep -v '^skills/' | head -5)
+```
+
+If non-empty:
+> These files are outside framework scope and won't be included:
+> {list}
+
+### Step 8: Stage framework files only
+
+```bash
+git add bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/ 2>/dev/null
+```
+
+If nothing staged: "No framework changes to submit." Stop.
+
+Commit message — per `.claude/context/commit-format.md`; use AskUserQuestion:
+
+```
+header: "Message"
+question: "Describe your contribution:"
+options:
+  - label: "{auto-derived from diff — e.g. 'fix(save): improve error handling'}"
+    description: "Based on your changes"
+  - label: "I'll write my own"
+    description: "Enter a custom message"
+```
+
+```bash
+git commit -m "$COMMIT_MESSAGE"
+```
+
+### Step 9: Safety scan
+
+Check for org-specific content that shouldn't go upstream:
+
+```bash
+ORG_NAME=$(jq -r '.org_name // empty' egregore.json 2>/dev/null)
+GITHUB_ORG=$(jq -r '.github_org // empty' egregore.json 2>/dev/null)
+SLUG=$(jq -r '.slug // empty' egregore.json 2>/dev/null)
+
+LEAKS=""
+for f in $DIFF_FILES; do
+  FOUND=$(grep -n "$ORG_NAME\|$GITHUB_ORG\|$SLUG" "$f" 2>/dev/null)
+  [ -n "$FOUND" ] && LEAKS="${LEAKS}\n${f}:\n${FOUND}"
+done
+```
+
+If leaks found, use AskUserQuestion:
+
+```
+header: "Safety"
+question: "Your changes contain org-specific references. Clean up before submitting?"
+options:
+  - label: "Fix first"
+    description: "I'll clean these up"
+  - label: "It's fine"
+    description: "False positives or intentional"
+```
+
+If "Fix first" → Stop.
+
+### Step 10: Push to fork
+
+```bash
+bash bin/contribute-guard.sh --expect "$UPSTREAM_REPO" >/dev/null || exit $?
+git push contribute "$CONTRIBUTE_BRANCH" -u --quiet 2>&1
+```
+
+If push fails: "Push failed. Your changes are saved locally. Check your network and try `/contribute submit` again." Stop.
+
+### Step 11: Create cross-fork PR
+
+```bash
+bash bin/contribute-guard.sh --expect "$UPSTREAM_REPO" >/dev/null || exit $?
+PR_URL=$(gh pr create \
+  --repo "$UPSTREAM_REPO" \
+  --head "${GH_USER}:${CONTRIBUTE_BRANCH}" \
+  --base main \
+  --title "$COMMIT_MESSAGE" \
+  --body "$(cat <<EOF
+$DESCRIPTION
+
+### Changes
+$(git diff upstream/main --stat -- bin/ .claude/commands/ .claude/agents/ loom/ CLAUDE.md skills/)
+
+---
+Contributed via \`/contribute\` from an Egregore instance.
+EOF
+)" 2>&1)
+```
+
+If PR creation fails: "PR creation failed, but your branch is pushed to your fork. Create the PR manually at github.com/{GH_USER}/{repo_name}." Stop.
+
+Extract PR number from URL.
+
+### Step 12: Confirmation
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  ↑ CONTRIBUTED                                  {author} · {date}   │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  {PR title}                                                          │
+│  → {UPSTREAM_REPO} · PR #{number}                                    │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  ✓ Pushed to fork · PR created                                      │
+│  {PR URL}                                                            │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+### Step 13: Return to working branch
+
+```bash
+git checkout "$PREVIOUS_BRANCH" 2>/dev/null || git checkout develop 2>/dev/null || true
+```
+
+### Step 14: Telemetry
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"contribute","subcommand":"submit"}' 2>/dev/null &
+```
+
+---
+
+## Status mode (`/contribute status`)
+
+```bash
+CONTRIBUTE_BRANCHES=$(git branch --list "contribute/*" --format="%(refname:short)")
+```
+
+For each branch, check:
+- Diff stat vs upstream/main
+- Whether pushed to fork (`git log contribute/$branch --oneline -1 2>/dev/null`)
+- Whether PR exists (`gh pr list --repo "$UPSTREAM_REPO" --head "${GH_USER}:${branch}" --json number,state --jq '.[0]' 2>/dev/null`)
+
+Display:
+
+```
+↑ Contributions to {UPSTREAM_REPO}
+
+  contribute/improve-save-command
+    +42/-8, 3 files · pushed · PR #17 (open)
+
+  contribute/fix-graph-sync
+    +8/-2, 1 file · local only · no PR
+
+  /contribute submit to push the current branch.
+```
+
+If no contribute branches: "No contributions in progress. Run `/contribute` to start one."
+
+---
+
+## Edge cases
+
+| Scenario | Handling |
+|----------|----------|
+| `upstream_url` is `"none"` | Executable guard refuses all contribution operations and redirects to `/save` |
+| `upstream_url` is empty | Executable guard selects `egregore-labs/egregore` |
+| Config is invalid or target changes | Executable guard fails closed before fork, push, or PR |
+| Fork already exists | `gh repo fork` is idempotent |
+| `contribute` remote exists | Skip adding |
+| No framework changes | "Make changes first, then `/contribute submit`" |
+| Org-specific refs in changes | Safety scan warns |
+| Already on `contribute/*` branch | Offer to submit or start new |
+| PR exists for this branch | Show existing PR URL, don't create duplicate |
+| Push fails | Preserve local changes, suggest retry |
+| PR creation fails | Branch is pushed, suggest manual PR |

package/runtime/claude/.claude/skills/create-skill/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: create-skill
+description: Create a skill your org owns — scaffolded in this Egregore, protected from framework updates, shared with teammates via /save.
+---
+
+Create an org-owned skill. Owned skills live in `.claude/skills/<name>/` like
+framework skills, but they belong to the org: `/update` never overwrites them,
+and if upstream ever ships a skill with the same name, the org's version wins
+and the collision is reported.
+
+Arguments: an optional skill name and/or a description of what the skill
+should do.
+
+## When to invoke
+
+User says: "create a skill", "make a skill for X", "I want a /foo command for
+our team", "turn this workflow into a skill", `/create-skill <name>`
+Not this: installing someone else's published skill → `find-skills` · changing
+a framework skill's behavior → `/contribute` (upstream owns it)
+
+## Step 1: Name and scope
+
+Derive a kebab-case name from the request. Rules:
+
+- Lowercase letters, digits, hyphens only. No slashes, no leading dot.
+- **Must not collide with a framework skill.** Check both the local tree and
+  upstream when available:
+
+```bash
+NAME="<kebab-name>"
+if [ -d ".claude/skills/$NAME" ]; then
+  echo "exists locally"
+fi
+git fetch upstream main --quiet 2>/dev/null || true
+git ls-tree -d upstream/main ".claude/skills/$NAME" 2>/dev/null | grep -q . && echo "exists upstream"
+```
+
+If the name exists locally or upstream, propose 2–3 alternatives via
+AskUserQuestion instead of silently picking one. An org CAN deliberately own a
+name upstream also uses (their version then always wins), but that is an
+explicit choice — never a default.
+
+If the user gave only a name and no behavior, ask what the skill should do
+before scaffolding — a skill with an empty body helps nobody.
+
+## Step 2: Scaffold
+
+Write `.claude/skills/$NAME/SKILL.md`:
+
+```markdown
+---
+name: <name>
+description: <one line — what it does and when an agent should reach for it>
+---
+
+<What this skill does, in 1–3 sentences.>
+
+## When to invoke
+
+User says: <trigger phrases>
+Not this: <adjacent intents that route elsewhere>
+
+## Steps
+
+1. <concrete step — commands in fenced bash blocks>
+2. <...>
+```
+
+Fill it with real content derived from the user's description — trigger
+phrases an agent can match, concrete steps, actual commands. Follow
+`product-voice` for any user-facing copy the skill emits.
+
+**Cross-runtime adapter (mandatory).** Codex invokes skills as `$<name>` from
+`.codex/skills/`, and Pi consumes the same tree — one adapter serves both.
+Write `.codex/skills/$NAME/SKILL.md`:
+
+```markdown
+---
+name: <name>
+description: '<same one line>'
+---
+
+<!-- org-owned skill adapter — created by /create-skill -->
+
+# <name> (org skill)
+
+This org-owned skill is defined once in `.claude/skills/<name>/SKILL.md`.
+
+1. Read `.claude/skills/<name>/SKILL.md` for the full workflow.
+2. Run any referenced `bin/` scripts directly from this shell.
+3. Translate interactive choices to this runtime's question tooling when
+   available; otherwise render compact numbered choices with an `Other:`
+   option and wait for the user.
+```
+
+The runtime installer only removes files it installed itself (hash-tracked),
+so this adapter survives Codex/Pi runtime upgrades. Without it, the skill
+exists for Claude Code teammates only — always write both files.
+
+## Step 3: Register ownership
+
+Add the name to `owned_skills` in `egregore.json` (create the array if
+absent):
+
+```bash
+jq --arg n "$NAME" '.owned_skills = ((.owned_skills // []) + [$n] | unique)' \
+  egregore.json > egregore.json.tmp && mv egregore.json.tmp egregore.json
+```
+
+This is what makes the skill org-owned: `/update` runs
+`bin/restore-owned-skills.sh` after every framework sync, which keeps every
+listed skill at the org's committed version.
+
+## Step 4: Share it
+
+Tell the user the skill is ready to try now (`/<name>` in Claude Code,
+`$<name>` in Codex, `/<name>` in Pi), then run `/save` so it reaches the team —
+teammates get it on `/pull` or their next session start. The skill directory,
+the `.codex/skills/` adapter, and the `egregore.json` change must all land in
+the same PR, or the ownership guarantee ships half-finished.
+
+Telemetry (fire-and-forget):
+
+```bash
+bash bin/telemetry.sh emit "command" '{"command":"create-skill"}' 2>/dev/null &
+```
+
+## Edge cases
+
+| Scenario | Handling |
+|---|---|
+| Name collides with a framework skill | Propose alternatives; owning a colliding name is explicit opt-in only. |
+| User wants to modify a framework skill | Route to `/contribute` — or, if they explicitly want an org-local fork, copy it under a NEW name, register ownership, and note the fork won't receive upstream improvements. |
+| Skill already in `owned_skills` | Editing an existing owned skill needs no re-registration — just edit and `/save`. |
+| No `jq` | Tell the user to add the name to `owned_skills` in `egregore.json` manually. |