agentleFS
akshaypimprikarakshaypimprikar/pragma/.claude/skills/sync-workflow/SKILL.md

sync-workflow

Skill4 starsChanged 4 days agoMITView on GitHub

Sync the pragma template repo so it stays consistent with a project's current conventions (build commands, branch strategy, agent conventions). Invoke manually after any change to those.

  • Commits and pushes

The file

We split this skill into the rules it gives an agent

11 rules. About 0 are common, 2 are distinctive, and 9 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 9

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run once a week, or before a pragma release, as one batch of every project change to AGENTS.md/CLAUDE.md, branch strategy, build commands, …

    line 12
  2. Very specific:

    Do this before making any edits below — pulling *after* step 4 has already staged uncommitted changes risks a checkout/pull conflict …

    line 23
  3. Very specific:

    All edits in steps 3-5 happen on this branch, not on develop directly.

    line 25
  4. Very specific:

    If checkout develop itself fails (e.g.

    line 27
  5. Distinctive:

    Read AGENTS.md (or CLAUDE.md on the pre-AGENTS.md convention) from your project — branch strategy, build commands, simulator name, …

    line 31
  6. Very specific:

    Read all files in .claude/skills/ — the project-specific versions

    line 32
  7. Very specific:

    Read all files in the pragma template repo's .claude/skills/

    line 35
  8. Very specific:

    Check for drift in these areas (keep <AppName> placeholders — pragma is a template):

    line 38
  9. Very specific:

    Leave project-only protected paths out of pragma (a domain-specific golden test, its _PROTECTED_FRAGMENTS entry and its self-test cases).

    line 54
  10. Very specific:

    After applying, run python3 scaffold/.claude/hooks/guard_protected_paths.py --self-test in pragma: 0 failures.

    line 56
  11. Distinctive:

    If nothing changed, do not create a branch or PR — report "no changes needed" instead.

    line 124

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Sync Workflow Agent

Sync the pragma template repo so it stays consistent with your project's current conventions.

Trigger

Run once a week, or before a pragma release, as one batch of every project change to AGENTS.md/CLAUDE.md, branch strategy, build commands, or agent conventions since the last sync: /sync-workflow

Do not port a project fix to pragma by hand as its own fix/* PR. It waits for the batch, where the sync lane's Synced from: line stands in for a second review of a change already reviewed in the project (2026-10-05: the same 4-line Gate 0 fix was reviewed twice). The exception is a fix that breaks pragma users today: sync it as soon as the project PR merges.

Process

0. Sync pragma's local checkout and create the sync branch first

git -C <pragma path> checkout develop && git -C <pragma path> pull
git -C <pragma path> checkout -B sync/<YYYY-MM-DD>

Do this before making any edits below — pulling after step 4 has already staged uncommitted changes risks a checkout/pull conflict against your own in-progress edits. All edits in steps 3-5 happen on this branch, not on develop directly. -B (not -b) resets the branch if a same-day sync attempt left one behind from an earlier aborted run. If checkout develop itself fails (e.g. mid-rebase), resolve or abort that first — don't work around it by editing on the wrong branch.

1. Read the source of truth

  • Read AGENTS.md (or CLAUDE.md on the pre-AGENTS.md convention) from your project — branch strategy, build commands, simulator name, architecture rules
  • Read all files in .claude/skills/ — the project-specific versions

2. Read the template

  • Read all files in the pragma template repo's .claude/skills/

3. Compare and update

Check for drift in these areas (keep <AppName> placeholders — pragma is a template):

What to checkSource of truth
Branch strategy (main vs develop)Your project's AGENTS.md/CLAUDE.md
Simulator nameYour project's AGENTS.md/CLAUDE.md
Build command structureYour project's AGENTS.md/CLAUDE.md
Test framework (import Testing vs XCTest)Your project's AGENTS.md/CLAUDE.md
Pre-flight check commands in /releaseYour project's /release skill
Architecture rules checklist in /reviewYour project's /review skill
New gates in /gates — only if generalizableYour project's /gates skill
CI workflow flags (simulator selection, coverage, parallelism)Your project's .github/workflows/*.yml vs. pragma's scaffold/.github/workflows/*.yml
Guard hook (PreToolUse, blocks gate-file edits on feature/*)Your project's .claude/hooks/guard_protected_paths.py vs. pragma's scaffold/.claude/hooks/guard_protected_paths.py: diff both ways (see below)

Guard hook rules. pragma changes this file on its own too, so your project is not always the source:

  • A change only in pragma's copy means your project is behind. Do not sync over it: port it to your project first in its own chore/* PR, then sync.
  • Leave project-only protected paths out of pragma (a domain-specific golden test, its _PROTECTED_FRAGMENTS entry and its self-test cases).
  • A synced change to PROTECTED_GLOBS needs the same change in pragma's scripts/check_gate_integrity.py GUARDED_PATH_GLOBS (the hook self-test compares them). That file is outside the sync lane, so open that sync as a chore/* pipeline PR, not sync/*. The same goes for any other synced change under scripts/.
  • After applying, run python3 scaffold/.claude/hooks/guard_protected_paths.py --self-test in pragma: 0 failures.

4. Apply updates

Edit only the lines that differ. Do not copy project-specific paths or app names into the template — use <AppName> placeholders.

For new gates in your project's /gates, judge each one individually — do not copy-paste:

  • Generalizable (checks a pattern any iOS MVVM+Repository project would want — e.g. a layer-rule compliance gate): port it as a templated gate with <placeholder> values, matching the style of Gates 1/2/7. Do not hardcode your project's literal grep patterns (field names, concrete paths, etc.) into the template.
  • App-specific (checks something only your project's domain or toolchain has — e.g. a concurrency-shape gate tied to one specific actor/service, or a visual-verification gate that depends on an MCP server the project installs itself): leave it out of pragma entirely. It has no equivalent in a template repo.

5. Self-review the diff before committing

Pragma has no AGENTS.md/CLAUDE.md and no /review of its own — this is the only check that runs before a sync PR opens. Keep it lightweight: it exists to catch the specific ways a template repo can drift, not to re-litigate content already reviewed once in your project. Run against the staged diff, before git commit — stage first, since the checks below read git diff --cached. Stage everything this sync touched, not just .claude/skills/ — a CI workflow flag change under scaffold/.github/workflows/ is just as much a sync output and must go through the same review:

git -C <pragma path> add .claude/skills/ scaffold/

a. No project-specific literals leaked into template content (advisory — eyeball each hit):

git -C <pragma path> diff --cached | grep -E '^\+' | grep -iE '<your real app name>|/Users/|iPhone [0-9]+|<a concrete ViewModel or Repository name>'

Fill in the alternation with your actual project's literal identifiers before running — e.g. <AppName>|/Users/<you>|iPhone <N>|<ConcreteViewModel>|<ConcreteRepository>, with each placeholder replaced by your project's real value. Searching for the placeholder text itself (<AppName> etc.) catches nothing; it's the literal values a leak would introduce that this check needs. A worked example in prose is fine (pragma's own files already do this, e.g. /gates feature/recurring-transactions). A hardcoded value standing in for what should be a <placeholder> is not — generalize it before committing.

b. <placeholder> convention held where your project's source used a concrete name: For every newly templated section (an architecture rule, a gate), confirm it uses <placeholder> tokens for anything project-specific — a type name, a file path, a field name — matching the style already used throughout pragma's gates/SKILL.md Gate 9/10 examples. Zero placeholders in a section that generalizes a project-specific check is the leak.

c. Gate numbering and counts stay internally consistent (deterministic): Gate 0 (the build-relevant change check) is intentionally excluded from both the sequence and the count — the pattern below starts from Gate 1 on purpose, not an oversight. deterministic-pr-gates/SKILL.md is excluded from the count-reference grep below: it's a standalone skill with its own independent gate numbering (one fewer than gates/SKILL.md), not a second copy of the same list.

awk 'BEGIN{expected=1} {if($1!=expected) print "non-sequential: expected "expected" got "$1; expected=$1+1}' \
  <(grep -oE '^### Gate [1-9][0-9]*' <pragma path>/.claude/skills/gates/SKILL.md | grep -oE '[0-9]+' | sort -n)
MAX=$(grep -oE '^### Gate [1-9][0-9]*' <pragma path>/.claude/skills/gates/SKILL.md | grep -oE '[0-9]+' | sort -n | tail -1)
if [ -z "$MAX" ]; then echo "ERROR: no '### Gate N' headers found in gates/SKILL.md — check the file, not the count"; else
grep -rniE "all [0-9]+ gates" <pragma path>/.claude/skills/*/SKILL.md | grep -v "deterministic-pr-gates/SKILL.md" | grep -viE "all $MAX gates"
fi

Pass: the sequential check prints nothing, and the count-reference grep returns no lines disagreeing with $MAX. Fail: fix the stale number before committing — a stale gate-count reference is a real recurring bug class, not a hypothetical one. If MAX comes back empty, gates/SKILL.md's header format has changed or the file is missing gate sections entirely — investigate that directly rather than trusting the count-reference grep (an empty $MAX would otherwise match every "all N gates" line as "stale," which is noise, not the real problem).

6. Open a PR — never push directly to main

The branch was already created in step 0. Re-stage before committing regardless of step 5's staging — if self-review in 5a/5b caught something and you fixed it, the fix is unstaged until you add it again:

git -C <pragma path> add .claude/skills/ scaffold/
git -C <pragma path> commit -m "chore: sync skills from <AppName> — <brief summary>"
git -C <pragma path> push -u origin sync/<YYYY-MM-DD>
gh pr create --repo akshaypimprikar/pragma \
  --title "chore: sync skills from <AppName> — <brief summary>" \
  --body "## Changes\n<bullet list of what changed and why>\n\n<append your coding agent's own PR-attribution footer here, if it uses one — e.g. Claude Code appends \"🤖 Generated with [Claude Code](https://claude.com/claude-code)\">" \
  --base develop \
  --head sync/<YYYY-MM-DD>

If nothing changed, do not create a branch or PR — report "no changes needed" instead.

Verify before trusting the PR: --repo alone does not fix the head branch — the shell's current working directory can silently resolve to the wrong repo's branch. Always confirm with:

gh pr view <N> --repo akshaypimprikar/pragma --json headRefName,baseRefName,files

7. Report

List every file changed and what was updated, plus the PR URL. If nothing needed changing, say so explicitly.

Done when

PR is open on pragma (or "no changes needed" confirmed), report delivered.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.