@skill-graph/cli 0.5.6

package/marketplace/skills/vercel-composition-patterns/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: vercel-composition-patterns
+description: "This skill provides React composition patterns that scale — compound components, render props, context providers, lifted state, and React 19 API changes. It applies when refactoring components with boolean prop proliferation, designing flexible component APIs, building reusable libraries, or reviewing component architecture — triggered by phrases like \\\\\\\"this component has too many props,\\\\\\\" \\\\\\\"design a compound component,\\\\\\\" \\\\\\\"make this more composable,\\\\\\\" \\\\\\\"refactor with render props,\\\\\\\" or \\\\\\\"component API design.\\\\\\\" Do NOT use for performance optimization — use react-best-practices instead."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-28\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-28\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"composition pattern\\\\\\\",\\\\\\\"compound component\\\\\\\",\\\\\\\"boolean prop\\\\\\\",\\\\\\\"render prop\\\\\\\",\\\\\\\"react composition\\\\\\\",\\\\\\\"context provider\\\\\\\",\\\\\\\"state explosion\\\\\\\",\\\\\\\"variant component\\\\\\\"]\",\"triggers\":\"[\\\\\\\"vercel-composition-patterns-skill\\\\\\\",\\\\\\\"react-composition-patterns-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"refactor\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/vercel-composition-patterns/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/vercel-composition-patterns/SKILL.md
+---
+# React Composition Patterns
+
+## Domain Context
+
+**What is this skill?** This skill provides React composition patterns that scale — compound components, render props, context providers, lifted state, and React 19 API changes. It applies when refactoring components with boolean prop proliferation, designing flexible component APIs, building reusable libraries, or reviewing component architecture — triggered by phrases like "this component has too many props," "design a compound component," "make this more composable," "refactor with render props," or "component API design." Do NOT use for performance optimization — use react-best-practices instead.
+## Key Files
+
+
+
+| File | Purpose |
+|---|---|
+| `skills/vercel-composition-patterns/PATTERNS.md` | Full composition guide with the canonical examples and decision rules this skill summarizes. |
+| `skills/vercel-composition-patterns/AGENTS.md` | Repo-local entry guidance for when to use composition patterns and how to choose among them. |
+| `skills/vercel-composition-patterns/rules/architecture-avoid-boolean-props.md` | Core rule for replacing boolean-prop APIs with composable structures. |
+| `skills/vercel-composition-patterns/rules/architecture-compound-components.md` | Compound component pattern guidance for shared-context component families. |
+| `skills/vercel-composition-patterns/rules/state-context-interface.md` | Provider contract pattern for exposing `state`, `actions`, and `meta`. |
+| `skills/vercel-composition-patterns/rules/patterns-explicit-variants.md` | Explicit variant pattern for named component modes instead of flag combinations. |
+
+## Coverage
+
+React component composition patterns that prevent boolean prop proliferation: compound components (shared context children), explicit variant components, children-over-render-props, context provider state/actions/meta interface, boolean state explosion audit, and the React 19 API migration (no forwardRef, use() over useContext()). Covers the refactor playbook from flag inventory through variant extraction to provider-based composition.
+
+## Philosophy
+
+Boolean props are technical debt that compounds exponentially. Every boolean added to a component doubles the state space, and most of those combined states are impossible or unsupported. Agents default to adding "just one more boolean" because it is the fastest path -- this skill forces the discipline of auditing the state explosion first. Without it, agents regularly create components with 5+ booleans and fragile if/else rendering chains that break on edge-case combinations.
+
+Composition patterns for building flexible, maintainable React components. Avoid
+boolean prop proliferation by using compound components, lifting state, and
+composing internals. These patterns make codebases easier for both humans and AI
+agents to work with as they scale.
+
+## Core Mandate
+
+- Never add boolean props to customize behavior.
+- If a component accumulates 3 or more booleans, treat the API as broken until proven otherwise.
+- Provider boundaries matter more than visual nesting; the provider owns state, actions, and meta.
+
+## When to Apply
+
+Reference these guidelines when:
+
+- Refactoring components with many boolean props
+- Building reusable component libraries
+- Designing flexible component APIs
+- Reviewing component architecture
+- Working with compound components or context providers
+
+## Rule Categories by Priority
+
+| Priority | Category                | Impact | Prefix          |
+| -------- | ----------------------- | ------ | --------------- |
+| 1        | Component Architecture  | HIGH   | `architecture-` |
+| 2        | State Management        | MEDIUM | `state-`        |
+| 3        | Implementation Patterns | MEDIUM | `patterns-`     |
+| 4        | React 19 APIs           | MEDIUM | `react19-`      |
+
+## Quick Reference
+
+### 1. Component Architecture (HIGH)
+
+- `architecture-avoid-boolean-props` - Don't add boolean props to customize
+  behavior; use composition
+- `architecture-compound-components` - Structure complex components with shared
+  context
+- `architecture-boolean-state-audit` - Count reachable vs impossible states before adding props
+
+### 2. State Management (MEDIUM)
+
+- `state-decouple-implementation` - Provider is the only place that knows how
+  state is managed
+- `state-context-interface` - Define generic interface with state, actions, meta
+  for dependency injection
+- `state-lift-state` - Move state into provider components for sibling access
+
+### 3. Implementation Patterns (MEDIUM)
+
+- `patterns-explicit-variants` - Create explicit variant components instead of
+  boolean modes
+- `patterns-children-over-render-props` - Use children for composition instead
+  of renderX props
+
+### 4. React 19 APIs (MEDIUM)
+
+> **⚠️ React 19+ only.** Skip this section if using React 18 or earlier.
+
+- `react19-no-forwardref` - Don't use `forwardRef`; use `use()` instead of `useContext()`
+
+## How to Use
+
+### Boolean State Explosion Audit
+
+Before adding a new prop or mode, answer:
+
+1. How many booleans does this component already have?
+2. How many combined states does that create?
+3. Which of those states are impossible, unsupported, or nonsensical?
+4. Can the valid states be named as explicit variants instead?
+
+If a boolean produces impossible combinations, stop and refactor the API.
+
+### Refactor Playbook
+
+1. Inventory flags and modes.
+2. Enumerate valid combinations.
+3. Delete impossible states.
+4. Name the remaining variants explicitly.
+5. Extract a provider that owns `state`, `actions`, and `meta`.
+6. Compose subcomponents around that contract.
+7. Add one example or test per valid variant.
+
+Read individual rule files for detailed explanations and code examples:
+
+```
+rules/architecture-avoid-boolean-props.md
+rules/state-context-interface.md
+```
+
+Each rule file contains:
+
+- Brief explanation of why it matters
+- Incorrect code example with explanation
+- Correct code example with explanation
+- Additional context and references
+
+## Verification
+
+After applying this skill, verify:
+- [ ] No component has 3+ boolean props without an explicit variant refactor
+- [ ] State is lifted into a context provider, not drilled through props
+- [ ] Compound components use children composition, not renderX props
+- [ ] React 19 code uses ref as regular prop and use() instead of useContext()
+- [ ] Impossible state combinations are documented and eliminated
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| React performance optimization (memoization, suspense) | `react-best-practices` | Performance skill owns rendering optimization |
+| Visual component design and styling | `visual-design` or `ux-ui-patterns` | This skill covers API shape, not visual appearance |
+| Next.js routing and server components | `next-best-practices` | Next.js skill owns framework-level patterns |
+
+## Full Compiled Document
+
+For the complete guide with all rules expanded: `AGENTS.md`

package/marketplace/skills/version-control/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: version-control
+description: "Use when designing or maintaining the shape of a repository's git history — choosing a branching model, deciding rebase vs merge, sizing commits, linking commits to tracker tickets, tagging releases, running parallel work across worktrees, and resolving the merge conflicts that arise from any of the above. Covers trunk-based development, short-lived feature branches, atomic commit discipline, linear-history conventions (rebase + squash), release tagging with annotated tags and SemVer, hotfix flows from tags, and worktree lifecycle for parallel agents or contributors. Do NOT use for the words inside the commit message (Conventional Commits format, identifier naming — use `naming-conventions`), for chasing a release-pipeline failure (use `debugging`), or for reviewing a PR's content (use `code-review`)."
+license: MIT
+compatibility: "Git-centric. Patterns translate to other DAG-based version-control systems (Mercurial, Jujutsu) with tool-specific syntax substitutions. Centralized systems (SVN, CVS) lack cheap branching and most of this skill's discipline does not apply."
+allowed-tools: Read Grep Bash Edit
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/version-control\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"version control\\\\\\\",\\\\\\\"git workflow\\\\\\\",\\\\\\\"branching strategy\\\\\\\",\\\\\\\"trunk-based development\\\\\\\",\\\\\\\"git flow\\\\\\\",\\\\\\\"short-lived branch\\\\\\\",\\\\\\\"feature branch\\\\\\\",\\\\\\\"merge vs rebase\\\\\\\",\\\\\\\"linear history\\\\\\\",\\\\\\\"atomic commit\\\\\\\",\\\\\\\"squash commit\\\\\\\",\\\\\\\"cherry-pick\\\\\\\",\\\\\\\"release tag\\\\\\\",\\\\\\\"annotated tag\\\\\\\",\\\\\\\"SemVer release\\\\\\\",\\\\\\\"hotfix branch\\\\\\\",\\\\\\\"git worktree\\\\\\\",\\\\\\\"parallel branch development\\\\\\\",\\\\\\\"commit provenance\\\\\\\",\\\\\\\"merge conflict resolution\\\\\\\",\\\\\\\"protected branch\\\\\\\"]\",\"examples\":\"[\\\\\\\"set up trunk-based development for a four-person team\\\\\\\",\\\\\\\"the main branch has 50 merge commits before release — clean up the history\\\\\\\",\\\\\\\"two agents are working in the same repo and clobbering each other's uncommitted changes — set up worktrees\\\\\\\",\\\\\\\"tag the v1.2.0 release with provenance back to the closing tracker milestone\\\\\\\",\\\\\\\"the feature branch is two weeks old and three weeks behind main — rebase or recreate?\\\\\\\",\\\\\\\"design the hotfix workflow for an urgent production patch off a release tag\\\\\\\",\\\\\\\"every commit must link back to a tracker ticket — what's the right enforcement layer?\\\\\\\",\\\\\\\"should we squash, rebase, or merge when integrating a feature branch?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"draft a Conventional Commits message for this change\\\\\\\",\\\\\\\"the release pipeline failed at the tag-creation step — find out why\\\\\\\",\\\\\\\"review this PR before we merge it\\\\\\\",\\\\\\\"explain our git policy to new contributors in the docs\\\\\\\",\\\\\\\"decide if this branching-rule change needs a regression test\\\\\\\",\\\\\\\"refactor the git helper scripts in our tooling repo\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"code-review\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"code-review evaluates the *content* of a change before merge; version-control owns the *shape* of history that change leaves behind\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"refactor\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"refactor reorganizes code without changing external behavior; version-control reorganizes history without changing the code's content (rebase, squash, cherry-pick)\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"naming-conventions owns commit-message wording (Conventional Commits prefix, scope, subject); version-control owns commit *boundaries* (what counts as one commit) and history *shape*\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"refactor\\\\\\\",\\\\\\\"naming-conventions\\\\\\\",\\\\\\\"debugging\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/version-control/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/version-control/SKILL.md
+---
+
+# Version Control
+
+## Coverage
+
+- Branching strategy selection: trunk-based development (default for product teams), Git Flow (only for shipped libraries with multiple supported versions), and the warning signs that a chosen model is failing
+- Atomic commit discipline: one logical change per commit, the test that distinguishes "atomic" from "small," and how to split a commit that snuck two changes together
+- History shape: rebase over merge for feature integration, squash on merge for keeping main linear, when to allow merge commits (rare — release branches with parallel hotfix history)
+- Provenance: the convention that every commit references its originating tracker ticket, and the enforcement options (commit-message hook, CI check, social convention)
+- Release tagging: annotated tags with provenance, SemVer 2.0.0 mapping, hotfix flow from a tag without polluting main
+- Worktree lifecycle: when to use worktrees, how to keep them clean, and the multi-agent failure mode worktrees prevent (parallel-session index contamination)
+- Path-limited commits: the `git commit --only -- <paths>` discipline that prevents a parallel session from injecting unrelated staged files into your commit
+- Conflict resolution: structural conflicts (one side renamed, one side edited) versus content conflicts; when to abandon a rebase and recreate the branch
+
+## Philosophy
+
+A repository's history is a *decision log*. When the log is noisy — merge commits where rebases would have been cleaner, multi-purpose commits that mix a fix with a feature, missing tracker IDs, branches that lived for a month — the team loses the ability to answer two questions that matter under pressure: *"why did this change?"* and *"can I revert just this without taking everything else with it?"* Both questions become archaeology rather than lookup.
+
+The correct mental model is: every commit is a transaction the future will need to read, often in a hurry, often by someone who was not in the meeting. The discipline is to keep transactions small, attributed, and reversible. A commit that combines a refactor with a bug fix cannot be reverted cleanly when the fix turns out to be wrong; a commit without a tracker ID forces the next reader into git-blame archaeology to reconstruct intent.
+
+The second principle is *cost asymmetry*. Cleaning up history *before* merge is cheap — squash, rebase, edit messages, split commits, all local operations on a feature branch. Cleaning up history *after* merge is expensive — it requires force-pushes, coordinated rewrites, and risks losing other people's work. Push the cleanup left to the moment the cost is lowest.
+
+The third principle, specific to multi-agent and multi-session work: the git index is a *process-shared mutex*. Two agents in the same repo share `.git/index`, which means a `git add` in one session lands in the other session's `git diff --cached`. The standard `git commit` command picks up everything currently staged. The defence is path-limited commits (`git commit --only -- <paths>`) that build a temporary index from explicitly-named paths only, ignoring whatever else a parallel session has staged. Without this discipline, multi-agent work produces commits with surprise files.
+
+## Branching Strategy: Trunk-Based by Default
+
+Trunk-based development is the right default for almost every product codebase: a single long-lived branch (`main`), short-lived feature branches that integrate frequently (every 1-2 days), and incomplete features merged behind feature flags rather than parked on long-running branches.
+
+| Rule | Why |
+|---|---|
+| Branches live < 48 hours | Forces small PRs, prevents drift from main, keeps merge cost low |
+| PRs target < 400 changed lines | Larger PRs review poorly; reviewer attention drops sharply past 400 lines |
+| Incomplete features ship behind flags | Lets you merge often without exposing half-built work to users |
+| `main` is always shippable | CI is the gate; nobody pushes broken code to main |
+
+The anti-pattern is a long-lived `develop` branch (Git Flow) used as if it were trunk: drift accumulates, integration becomes its own project, and "merging develop to main" becomes a quarterly event with thousands of changed files. Git Flow exists for a different problem — shipping libraries with multiple supported major versions, where you genuinely need parallel release branches. If you are not maintaining `v1.x` and `v2.x` simultaneously, you do not need Git Flow.
+
+## Commit Authoring: One Change, One Commit
+
+A commit is "atomic" when reverting it produces no broken intermediate state, no accidentally-reverted unrelated work, and no half-finished features. The test:
+
+> *If a senior reviewer asks "why does this commit exist?" and the answer requires the word "and," split the commit.*
+
+A commit titled "fix order rounding bug AND clean up the order utils file" is two commits. Run `git rebase -i HEAD~1` and split before merging.
+
+The commit-message wording (verb tense, prefix conventions, character limits) is *naming* — see `naming-conventions` for that. Version-control owns the commit *boundaries*: what counts as one commit, where one ends and the next begins, and whether the commit can stand alone if every later commit is reverted.
+
+### Provenance: Linking Commits to Tracker Tickets
+
+Every commit on a feature branch should link to the tracker ticket that produced it. The format is convention-driven; common forms:
+
+```
+feat(orders): add CSV export button (PROJ-1234)
+
+Implements the export button on the order list. Output mirrors the
+table columns; encoding is UTF-8 with BOM for spreadsheet compatibility.
+```
+
+The tracker ID may live in the subject (visible in `git log --oneline`) or in a structured trailer (`Refs: PROJ-1234`, machine-parseable for automated cross-linking). Pick one and apply it consistently — mixing both fragments the searchable history.
+
+If the change implements an architecture decision, reference the decision document in the commit body so future readers can find the why:
+
+```
+refactor(persistence): replace ad-hoc SQL with repository pattern (PROJ-1290)
+
+Implements the data-access pattern decided in docs/decisions/0017-repository-pattern.md.
+The change is mechanical; behavior is preserved by the existing integration tests.
+```
+
+## History Shape: Rebase, Squash, Linear
+
+For feature-branch integration into main, prefer this order:
+
+1. **Rebase the feature branch onto main** before merging. This re-applies your commits on top of the latest main, replacing "merge main into feature" noise with a clean linear history.
+2. **Squash on merge** if the feature branch has multiple commits that only make sense together. The PR becomes one commit on main; the feature-branch detail lives in the PR description and the squashed commit body.
+3. **Allow real merge commits** only when both branches have valuable independent history (rare — usually a release branch and a hotfix branch).
+
+```bash
+# Local workflow, on a feature branch
+git fetch origin
+git rebase origin/main          # replay your commits on top of latest main
+# resolve any conflicts, run tests, push
+git push --force-with-lease     # safe force: rejects if remote moved since your last fetch
+
+# Merging the PR into main (in your forge UI or CLI)
+# Pick "Squash and merge" if the branch has noisy WIP commits
+# Pick "Rebase and merge" if every commit is publishable on its own
+# Avoid "Create a merge commit" by default
+```
+
+`--force-with-lease` is the safe variant of `--force`: it pushes only if the remote branch is at the SHA you last fetched, refusing if a collaborator pushed in between. Plain `--force` overwrites whatever is there, which destroys other people's work.
+
+## Release Tagging
+
+Releases are *annotated* tags (`git tag -a`), not lightweight tags. Annotated tags carry a tagger identity, a date, and a message — they are first-class objects in the git store and survive history rewrites that would orphan a lightweight tag.
+
+```bash
+git tag -a v1.2.0 -m "Release v1.2.0 — closes Milestone 4 (PROJ-MS-4)"
+git push origin v1.2.0
+```
+
+Tag names follow SemVer 2.0.0 (`MAJOR.MINOR.PATCH`, optional pre-release suffix `-rc.1` or `-beta.2`). Patch tags are cheap; cut one per shipped fix.
+
+### Hotfix Flow
+
+When production has a bug that cannot wait for the next scheduled release:
+
+```bash
+# 1. Branch from the latest release tag, not from main
+git checkout -b hotfix/v1.2.1 v1.2.0
+
+# 2. Apply the minimal fix; test; commit
+git commit -m "fix(orders): rounding error in tax calculation (PROJ-1305)"
+
+# 3. Tag the patch
+git tag -a v1.2.1 -m "Hotfix v1.2.1 — tax rounding (PROJ-1305)"
+git push origin v1.2.1
+
+# 4. Cherry-pick the fix back to main so the bug doesn't return next release
+git checkout main
+git cherry-pick <hotfix-commit-sha>
+git push origin main
+```
+
+The hotfix branch can be deleted after the cherry-pick. The discipline is to keep `main`'s history linear *and* keep the hotfix tag pointing at the minimal fix, not at a snapshot of main.
+
+## Worktrees: Parallel Work Without Contamination
+
+Worktrees let multiple checkouts of the same repository coexist on different branches in different filesystem directories — without the cost of a full clone and without the conflict of a single working tree being on multiple branches.
+
+```bash
+# Create a worktree for a parallel feature
+git worktree add ../my-repo-feature-A feature/A
+
+# List current worktrees
+git worktree list
+
+# Remove a worktree after the work is merged
+git worktree remove ../my-repo-feature-A
+```
+
+Worktrees are essential when:
+
+- Multiple agents or contributors are working in the same repo simultaneously and would otherwise overwrite each other's uncommitted changes
+- You want to run a long task (test suite, build) on one branch while editing on another
+- You need to inspect a release tag's tree without disrupting your in-progress work
+
+The cleanup discipline matters: an abandoned worktree directory does not free its branch lock; `git worktree list --porcelain` and `git worktree prune` are the cleanup tools.
+
+## Path-Limited Commits
+
+In any repository where multiple processes or sessions share the working tree, the standard `git commit` is unsafe. The git index is a process-shared mutex; another session's `git add` lands in your `git diff --cached`, and a later `git commit` picks it up.
+
+The defence:
+
+```bash
+# Right — for tracked files: build a temporary index from these paths only
+git commit --only -- path/one path/two -m "..."
+
+# Right — for new files: add first, then commit with --only
+git add path/one path/two
+git commit --only -- path/one path/two -m "..."
+
+# Wrong — picks up whatever a parallel session has staged
+git add path/one
+git commit -m "..."
+```
+
+`--only` builds a transient index containing only the listed paths and commits from that. Whatever a parallel session has in the real index is left untouched for that session to commit. The safety window closes at the `git commit --only` call, not at the `git add`.
+
+After every commit, verify the file list:
+
+```bash
+git show --stat HEAD
+```
+
+If files you did not intend to commit appeared, a parallel session staged them between your `git add` and your `git commit`. The recovery is `git reset --soft HEAD^` and a retry with `--only`.
+
+## Merge Conflict Resolution
+
+Conflicts come in two shapes:
+
+**Content conflicts** — both sides edited the same lines. Resolution is line-by-line judgment, often informed by reading the surrounding context to understand what each side was trying to achieve.
+
+**Structural conflicts** — one side renamed a file, moved a function, or changed a dependency boundary while the other side edited the old shape. Git frequently reports these as "added by us / deleted by them" or "modified by both" with surprising contents. The resolution is rarely a textual merge; it is a re-application of the smaller change against the new shape.
+
+When a rebase produces conflicts on every replayed commit (a sign the branch and main have diverged structurally), the right move is often to abandon the rebase, recreate the branch from current main, and cherry-pick or re-author the changes:
+
+```bash
+git rebase --abort
+git checkout main && git pull
+git checkout -b feature/x-redo
+# re-author the changes against the current main shape
+```
+
+A rebase that requires resolving the same conflict in five replayed commits is a signal — the branch is too old and the cleanup cost has crossed the recreate threshold.
+
+## Verification
+
+- [ ] Branching model is named explicitly (trunk-based or Git Flow), and the team's actual behavior matches the named model
+- [ ] Feature branches stay short-lived (under 48 hours typical, under one week absolute)
+- [ ] Every commit on a feature branch is atomic — reverts cleanly without taking unrelated work
+- [ ] Every commit links to a tracker ticket via convention (subject suffix or `Refs:` trailer), enforced by hook or CI when feasible
+- [ ] PRs are integrated via rebase-and-merge or squash-and-merge by default; explicit merge commits only for cross-branch releases
+- [ ] Releases are annotated tags following SemVer 2.0.0
+- [ ] Hotfixes branch from the relevant release tag, are tagged with a patch increment, and are cherry-picked back to main
+- [ ] Worktrees are used for any work that runs alongside other in-progress work in the same repo
+- [ ] Commits in multi-session repos use `git commit --only -- <paths>` to prevent parallel-session index contamination
+- [ ] `git push --force-with-lease` is the only force-push form ever used; plain `--force` is treated as a destructive operation
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `naming-conventions` | Writing the commit message itself (Conventional Commits prefix, scope, subject wording, identifier names) |
+| `documentation` | Drafting the contributor-docs page that explains your version-control policy |
+| `code-review` | Reviewing a PR's content for correctness, style, or design |
+| `refactor` | Reorganizing the code that the commits touch — version-control reorganizes the *commits*, refactor reorganizes the *code* |
+| `debugging` | Chasing a release-pipeline failure or a broken hotfix tag |
+| `testing-strategy` | Deciding whether a change to the branching policy itself needs a regression test |

package/marketplace/skills/visual-design-foundations/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: visual-design-foundations
+description: "Use when designing or auditing visual craft: color palette, typography, spacing, elevation, rhythm, density, visual hierarchy, brand fit, contrast intent, and motion feel. Do NOT use for sign-system meaning (use `semiotics`), token/component architecture (use `design-system-architecture`), responsive structure (use `layout-composition`), or accessibility compliance (use `a11y`)."
+license: MIT
+compatibility: "Portable visual-design guidance for product UI, dashboards, docs, marketing-adjacent product surfaces, and design-system consumers. Does not replace brand-specific guidelines."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/visual\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-11\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-11\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"visual-design\\\\\\\",\\\\\\\"visual craft\\\\\\\",\\\\\\\"palette direction\\\\\\\",\\\\\\\"typography direction\\\\\\\",\\\\\\\"spatial rhythm\\\\\\\",\\\\\\\"density rules\\\\\\\",\\\\\\\"elevation treatment\\\\\\\",\\\\\\\"motion feel\\\\\\\",\\\\\\\"brand fit\\\\\\\"]\",\"examples\":\"[\\\\\\\"pick a visual direction for this dashboard without changing the task structure\\\\\\\",\\\\\\\"audit color, typography, spacing, and hierarchy for this product page\\\\\\\",\\\\\\\"this UI feels flat and hard to scan - improve the visual hierarchy\\\\\\\",\\\\\\\"choose a restrained palette and type scale for an internal admin tool\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"what does this icon or badge color communicate to users?\\\\\\\",\\\\\\\"define semantic tokens and component variants\\\\\\\",\\\\\\\"decide the responsive section order and breakpoint behavior\\\\\\\",\\\\\\\"verify WCAG contrast, focus order, and screen-reader behavior\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"semiotics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"semiotics owns what visual signs mean; visual-design-foundations owns the craft choices that shape the surface\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"design-system-architecture owns reusable tokens and components; visual-design-foundations owns visual direction and craft on a surface\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"layout-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"layout-composition owns responsive structure; visual-design-foundations owns palette, typography, rhythm, density, and polish\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns accessibility compliance; visual-design-foundations can propose visual choices that a11y later verifies\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"semiotics\\\\\\\",\\\\\\\"design-system-architecture\\\\\\\",\\\\\\\"layout-composition\\\\\\\",\\\\\\\"microcopy\\\\\\\",\\\\\\\"a11y\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"a11y\\\\\\\",\\\\\\\"semiotics\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/visual-design-foundations/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/visual-design-foundations/SKILL.md
+---
+
+# Visual Design Foundations
+
+## Coverage
+
+Design and audit visual craft for interface surfaces. Covers palette direction, type scale, spacing rhythm, hierarchy, density, elevation, borders, contrast intent, visual weight, motion feel, brand fit, and when a visual system should be split into deeper color, typography, or motion skills.
+
+## Philosophy
+
+Visual design is not decoration after structure; it is how the structure becomes legible. Good visual craft makes priority, grouping, affordance, and tone visible without asking the user to parse every label.
+
+Keep this skill at foundation level. If the task needs formal color math, font-loading engineering, or token governance, hand off to the skill that owns that contract.
+
+## Method
+
+1. Name the surface type: operational tool, docs, dashboard, editorial page, marketplace, or brand page.
+2. State the intended tone and scanning demand.
+3. Choose palette roles before picking raw colors: surface, text, accent, success, warning, danger, info, disabled.
+4. Define type roles: page title, section heading, control label, body, metadata, numeric emphasis.
+5. Set spacing and density rules that match repeated use, not one screenshot.
+6. Use elevation, border, and background only to clarify grouping or affordance.
+7. Check visual decisions against `semiotics` and `a11y` before treating them as done.
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/visual-design-foundations.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/visual-design-foundations.json). The checklist below is the authoring gate for visual-design decisions; the eval file is the grader surface.
+
+## Verification
+
+- [ ] Visual hierarchy makes primary content faster to find
+- [ ] Palette roles are named by purpose rather than raw color
+- [ ] Type roles are consistent and not oversized inside compact UI
+- [ ] Spacing and density fit the surface's repeated-use context
+- [ ] Elevation and borders clarify grouping instead of adding noise
+- [ ] Motion, if used, clarifies state or continuity and can be reduced
+- [ ] A11y contrast and non-color-only checks are deferred to `a11y`
+
+## Do NOT Use When
+
+| Use instead | When |
+|---|---|
+| `semiotics` | The question is what a color, icon, badge, shape, or visual metaphor means. |
+| `design-system-architecture` | The task is semantic tokens, component APIs, theming contracts, or governance. |
+| `layout-composition` | The task is responsive structure, grid tracks, breakpoints, or section order. |
+| `a11y` | The task is WCAG contrast, focus, labels, keyboard access, or assistive technology. |
+| `microcopy` | The task is the wording inside buttons, dialogs, empty states, errors, or tooltips. |

package/marketplace/skills/visual-hierarchy/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: visual-hierarchy
+description: "Use when establishing visual hierarchy — type scale ratios, spacing rhythm, contrast as ordering signal, weight and size as importance, and the layered relationship between primary, secondary, and tertiary information. Do NOT use for content writing, information architecture, or specific color palette construction."
+license: CC-BY-4.0
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-12\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-12\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"visual hierarchy\\\\\\\",\\\\\\\"hierarchical type sizing\\\\\\\",\\\\\\\"proximity hierarchy\\\\\\\",\\\\\\\"contrast hierarchy\\\\\\\",\\\\\\\"importance ordering\\\\\\\",\\\\\\\"reading order\\\\\\\",\\\\\\\"focal point\\\\\\\",\\\\\\\"figure ground\\\\\\\",\\\\\\\"gestalt principles\\\\\\\",\\\\\\\"hierarchy through weight\\\\\\\",\\\\\\\"hierarchy through size\\\\\\\",\\\\\\\"button hierarchy\\\\\\\",\\\\\\\"primary secondary tertiary actions\\\\\\\"]\",\"triggers\":\"[\\\\\\\"visual hierarchy\\\\\\\",\\\\\\\"type as hierarchy\\\\\\\",\\\\\\\"what should the eye go to first\\\\\\\",\\\\\\\"establishing focus\\\\\\\",\\\\\\\"page hierarchy\\\\\\\"]\",\"examples\":\"[\\\\\\\"Decide the H1/H2/H3 size ratios and weight contrast for a long-form article layout\\\\\\\",\\\\\\\"Reduce visual noise on a dashboard where every element competes for attention\\\\\\\",\\\\\\\"Establish a clear primary call-to-action on a page with multiple secondary actions\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"Write the H1 copy that should appear at the top of the landing page\\\\\\\",\\\\\\\"Choose between sans-serif and serif typefaces for the brand\\\\\\\",\\\\\\\"Pick the brand's primary color\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"typography-system\\\\\\\",\\\\\\\"color-system-design\\\\\\\",\\\\\\\"layout-composition\\\\\\\",\\\\\\\"visual-design-foundations\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"typography-system\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"typography-system defines the scale and the typefaces; this skill decides how to deploy them as hierarchy signals on a given surface.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"layout-composition\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"layout-composition handles grid, alignment, and spatial structure; this skill handles the prioritization within a layout.\\\\\\\"}]}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/visual-hierarchy/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/visual-hierarchy/SKILL.md
+---
+
+# Visual Hierarchy
+
+## Coverage
+Visual hierarchy is the ordering of perceptual prominence that tells a reader what to look at first, second, and third. The available signals are scale (larger draws attention before smaller), weight (heavier strokes draw attention before lighter), contrast (higher contrast against the background reads before lower), color (saturated and warm colors read before desaturated and cool), position (top-left in left-to-right reading cultures reads first; centered isolated elements break flow and draw focus), and isolation (whitespace around an element increases its prominence regardless of its intrinsic properties).
+
+Type scale operationalizes scale as hierarchy. Modular scales — pairs of values related by a ratio (1.125 major second, 1.2 minor third, 1.25 major third, 1.333 perfect fourth, 1.414 augmented fourth, 1.5 perfect fifth, 1.618 golden ratio) — produce step sizes that feel intentional. The ratio chosen determines the perceptual distance between levels: a 1.125 ratio gives subtle hierarchy useful for content-dense interfaces; a 1.5 ratio gives loud hierarchy useful for marketing surfaces. Most production systems use 5–7 type sizes; more sizes dilute hierarchy by giving the reader too many similar steps.
+
+Spacing creates hierarchy through proximity (Gestalt's law of proximity — items closer together read as grouped, items further apart read as separate) and through breathing room (an element with more whitespace around it reads as more important). Vertical rhythm — a consistent baseline grid that spacing values snap to — reinforces grouping without explicit dividers and makes the page feel calmer because the eye finds predictable resting points.
+
+Contrast as ordering is more general than color contrast. Two equal-sized headlines can be ordered by weight (bold reads before regular), by color (filled black reads before mid-gray), or by treatment (underlined or boxed reads before plain). The principle: when two elements compete for attention, increase the difference along one dimension rather than incrementing many dimensions slightly. Loud-loud combinations exhaust the reader; one loud against many quiet directs them.
+
+## Philosophy
+Hierarchy is what you suppress, not what you amplify. Making one thing important by making everything else louder produces a flat, noisy surface where nothing is important. The discipline is restraint: most elements should be quiet so the few that need to be loud can be heard.
+
+Reading order is a property of the page, not just the markup. CSS source order, visual size, color contrast, and position all participate. When they disagree — a giant pull quote in the middle of an article, an overlay button that contrasts more than the page title — the reader's eye follows the visual cues regardless of the writer's intent. Verify hierarchy by asking what someone notices first, second, and third without reading.
+
+## Verification
+- Squinting at the surface (or rendering it at low resolution) reveals an unambiguous order of attention; the intended first element is the first noticed.
+- Type scale uses at most 7 sizes; each level differs from its neighbor enough to register as different at a glance.
+- Whitespace around a primary element is larger than whitespace around its neighbors, not equal to them.
+- A grayscale screenshot retains the intended hierarchy; if hierarchy collapses without color, the design is over-reliant on hue.
+- Primary calls to action appear at most once per view; if two CTAs are present, one is visibly secondary in weight or fill.
+- Adjacent elements at the same hierarchy level share scale, weight, and color treatment; deviations are deliberate and signal a meaningful difference.
+- Reading the page aloud in the order the eye lands on elements matches the order intended by the content.
+
+## Do NOT Use When
+- The task is writing the copy itself rather than ordering it visually. Hierarchy without good copy emphasizes the wrong things.
+- You are deciding how to structure a site's navigation or content taxonomy. That is information architecture, not visual hierarchy.
+- The decision is which typeface to use or which color the brand should adopt. Use typography-system or color-system-design.
+- The concern is grid structure, alignment, or column composition. Use layout-composition.
+- The accessibility question is contrast ratios for WCAG compliance. Use a11y for the threshold; this skill for the design intent.