Skip to main content

Propose team rule

This skill turns a candidate team rule into a reviewable PR on bewith-dev/bewith-docs. The rule lands as a standalone file under .claude/rules/team/ so the team can discuss it on the PR before deciding where it ultimately belongs (CLAUDE.md, an agent body, a policy, or kept as-is).

When to invoke​

Auto-invoke (after explicit user approval):

When you're about to save a memory and the insight applies generically — to any bewith-dev developer working in any repo, not just to this specific user or project — pause. Ask:

"נראה לי שזה רלוונטי גם לאחרים בצוות. רוצה שאפתח PR לכללי הצוות כדי שנדון בזה?"

(or in English, matching the conversation's language)

If they confirm, invoke this skill. If they decline or say "this is personal," save it as personal memory instead per the usual auto-memory flow.

Manual entry point: /share-rule [optional one-line description].

Generic vs personal — the discrimination​

Personal (save as memory, don't propose)Generic (propose as team rule)
"Ariel prefers terse responses in Hebrew""Estimate work in hours, not weeks, when Claude is the implementer"
"Ariel is currently working on the Attendance app""Always check for active users before changing a sheet schema"
"Ariel's manager is X, HR is Y""Pay periods at BeWith run 25→24 of the month"
"This branch is for hotfix T-123""PRs to master require typecheck + branch name feature/<slug>"
References to specific tickets, files, or commitsPatterns, conventions, anti-patterns, non-obvious gotchas

Edge case: a strong personal preference that most developers would also benefit from. Ask the developer — let them decide.

Steps​

1. Confirm the rule content with the developer​

Restate what you're about to propose in one or two sentences. Get explicit confirmation. Example:

"אני הולך לפתוח PR שמציע: 'בכל סקופ של פיצ'ר, בדוק קודם אם יש משתמשים פעילים לפני שאתה מציע migration logic.' מאשר?"

If the developer wants to wordsmith first, edit together before opening the PR. Once approved:

2. Audit existing rules to prevent duplication​

Before drafting, grep the platform for overlap:

# Look for any existing rule on a similar topic
grep -rn "<key-phrase-from-the-rule>" \
  "$BEWITH_DIR/.claude/rules/team/" \
  "$BEWITH_DIR/.claude/agents/" \
  "$BEWITH_DIR/CLAUDE.md" \
  "$BEWITH_DIR/templates/consumer-repo/CLAUDE.md" 2>/dev/null

If a rule on the same topic already exists, prefer updating it (open a PR against that file) over creating a new one. State the overlap to the developer and let them pick.

3. Locate the bewith-docs checkout​

Follow the canonical resolution cascade in docs/methodology/session-safety.md — "Locating the bewith-docs checkout". Set BEWITH_DIR=<resolved path> and continue.

The cascade lives in one place so all state-mutating skills inherit any future change. Do not restate it here.

4. Pre-flight safety checks​

These checks prevent collisions and data loss across concurrent sessions:

# 4a. Generate the rule slug (kebab-case, short)
SLUG="<derived-from-rule-title>"
BRANCH="proposal/team-rule-${SLUG}"     # single segment — a nested slash (proposal/team-rule/x) fails branch-name-check

# 4b. Refuse if the branch already exists locally or remotely
git -C "$BEWITH_DIR" fetch origin master --quiet
if git -C "$BEWITH_DIR" rev-parse --verify --quiet "refs/heads/${BRANCH}" >/dev/null; then
  echo "ERROR: branch ${BRANCH} already exists locally. Pick a different slug or delete the stale branch." >&2
  exit 1
fi
if git -C "$BEWITH_DIR" ls-remote --exit-code origin "${BRANCH}" >/dev/null 2>&1; then
  echo "ERROR: branch ${BRANCH} already exists on remote. Probably an in-flight proposal — check open PRs first." >&2
  exit 1
fi

Tell the developer what you found if either check fails. Do not "fix" by mutating their branches.

5. Create an isolated worktree​

Never operate on the developer's working tree. A concurrent session may be editing it.

WORKTREE="$(mktemp -d -t bewith-team-rule.XXXXXXXX)"
git -C "$BEWITH_DIR" worktree add -b "${BRANCH}" "${WORKTREE}" origin/master
# Pre-commit validators import js-yaml etc.; a fresh worktree has no node_modules.
ln -s "$BEWITH_DIR/node_modules" "${WORKTREE}/node_modules"

The worktree is a separate working directory pointing at the same .git data store. The developer's primary worktree is untouched.

6. Draft the rule file​

Write to ${WORKTREE}/.claude/rules/team/${SLUG}.md with this exact frontmatter shape:

---
name: <slug>
description: <one-line summary — what the rule says, in present tense>
status: proposed
proposed_by: <developer's git user.name>
proposed_from: <name of the repo where the insight surfaced, e.g. "backend-api">
---

# <Human title>

<One-paragraph statement of the rule in plain English.>

**Why:** <The motivating reason — a past incident, an explicit user request, a constraint. One or two sentences.>

**How to apply:** <Concrete guidance — when this rule fires, what to do instead. One or two sentences.>

**Scope:** <Which repos / agents / situations this applies to. If "all bewith-dev repos," say so.>

## Examples (optional)

- ✅ <a concrete case where applying the rule helps>
- ❌ <a concrete case where ignoring the rule hurts>

All content in English (per feedback-artifact-language). Chat with the developer can be Hebrew; the artifact must be English.

7. Commit + push + open PR​

cd "${WORKTREE}"
git add ".claude/rules/team/${SLUG}.md"
git commit -m "$(cat <<EOF
proposal(team-rules): ${SLUG}

Auto-generated by /share-rule from a session in <source-repo-name>.

EOF
)"
git push -u origin "${BRANCH}"

gh pr create \
  --title "proposal(team-rules): ${SLUG}" \
  --body "$(cat <<EOF
## Proposed team rule

See \`.claude/rules/team/${SLUG}.md\` in the diff.

## Why this came up

<one paragraph — the conversation context, the decision the developer made, why this felt team-applicable>

## Source

- Developer: <git user.name>
- Repo at the time: <source-repo-name>
- Approved via: <"explicit /share-rule call" | "Claude proposed, developer confirmed">

## Discussion checklist

- [ ] Does this rule apply broadly enough to land in the platform?
- [ ] Right home: keep as standalone in \`.claude/rules/team/\`, fold into \`CLAUDE.md\`, attach to an agent body, or formalize as a policy?
- [ ] Anything missing from the \`Why\` / \`How to apply\` text?
- [ ] Existing rules to update or supersede?

🤖 Generated with [Claude Code](https://claude.com/claude-code) via /share-rule
EOF
)"

After the PR is created, capture the URL and surface it to the developer.

8. Cleanup the worktree​

Always run, even on failure paths:

git -C "$BEWITH_DIR" worktree remove --force "${WORKTREE}"

The remote branch and PR remain — only the local temporary worktree is removed. Use git -C "$BEWITH_DIR" worktree list if you need to verify nothing was left behind.

9. Record what you did​

After success, save a personal memory in the developer's own memory store marking that this rule was proposed (so you don't re-propose the same thing). Format:

---
name: <slug>-proposed
description: Proposed team rule "<title>" — PR #<num>. Status pending.
metadata:
  type: project
---
Proposed via /share-rule on <date>. PR: <url>. Don't re-propose until the PR resolves.

This goes in the developer's normal personal memory directory — same place auto-memory writes.

Anti-patterns​

  • Touching the developer's working tree. Always use a worktree. Never cd into $BEWITH_DIR and run git commands that mutate state. If you find yourself wanting to git checkout in the primary worktree, you're doing it wrong.
  • Auto-invoking without explicit user approval. Every PR opened by this skill consumes the team's review attention. Don't surprise people.
  • Re-proposing the same rule across sessions. Check your personal memory for a <slug>-proposed marker before invoking.
  • Personal preferences disguised as conventions. "Ariel prefers terse responses" is not a team rule. If only one developer benefits, save to personal memory.
  • Authoring the rule file in Hebrew. The artifact must be English. Chat can be Hebrew.
  • Force-pushing or amending after the PR opens. Push fixes as new commits so reviewers see the iteration. Only the developer can --force-with-lease their own proposal branch.
  • Deleting the worktree mid-operation. Cleanup happens last, after the PR is open.

Cross-references​