Git-based package registry for VibeSpec specifications

This is the official registry for VibeSpec packages. Instead of requiring a dedicated server, this registry uses Git as the storage and distribution mechanism, leveraging existing Git hosting platforms (GitHub, GitLab, Gitee, etc.).

✅ No server deployment required - Use GitHub, GitLab, or any Git host ✅ Free hosting - Leverage free Git hosting services ✅ Built-in version control - Git history tracks all changes ✅ Access control - Use Git repository permissions ✅ Reliable & distributed - Git's proven infrastructure ✅ Works offline - Clone once, use anywhere

vibespec-registry/
├── index.yaml                      # Package index for fast lookup
├── packages/
│   ├── @vibespec/
│   │   ├── go-api/
│   │   │   ├── 1.0.0/             # Version directory
│   │   │   │   ├── package.yaml
│   │   │   │   ├── specs/
│   │   │   │   ├── skills/
│   │   │   │   └── knowledge/
│   │   │   ├── 1.2.3/
│   │   │   │   └── ...
│   │   │   └── latest -> 1.2.3    # Symlink to latest (optional)
│   │   └── git-vcs/
│   │       └── 1.0.0/
│   └── @myorg/                    # Custom organization scope
│       └── custom-spec/
└── README.md                       # This file

Edit your project's .vibespec/vibespec.yaml:

registries:
  # Official Git registry
  - name: official
    type: git
    url: https://github.com/vibespec/registry.git
    branch: main  # optional, default: main

  # Your company's private registry
  - name: company
    type: git
    url: https://github.com/mycompany/vibespec-registry.git
    branch: main

  # GitLab example
  - name: gitlab
    type: git
    url: https://gitlab.com/myorg/specs.git

  # Gitee example (China)
  - name: gitee
    type: git
    url: https://gitee.com/myorg/vibespec-registry.git

# Install from official Git registry
vibespec install @vibespec/go-api

# Install from specific registry
vibespec install @vibespec/go-api --registry official

# Install specific version
vibespec install @vibespec/go-api@1.2.3

# Auto-install based on project detection
vibespec install --auto

# Search in all registries
vibespec search go

# Search in specific registry
vibespec search go --registry official

vibespec list

1. First time: CLI clones the registry repository to local cache (~/.vibespec/cache/git-registries/)
2. Subsequent uses: CLI pulls latest changes (cached for 5 minutes)
3. Package installation: Copies package files from cache to project .vibespec/ directory
4. Offline support: Once cloned, works without internet

# Create repository
mkdir my-vibespec-registry
cd my-vibespec-registry

# Initialize Git
git init

# Create structure
mkdir -p packages/@myorg/my-spec/1.0.0

# Create your spec package
cd packages/@myorg/my-spec/1.0.0

# Create package.yaml
cat > package.yaml <<EOF
name: "@myorg/my-spec"
version: "1.0.0"
description: "My custom specifications"
license: MIT

match:
  stacks:
    - name: go
  domains: []

contents:
  specs:
    - id: my-coding-style
      file: specs/coding-style.spec.md
      priority: 100
EOF

# Add your spec files
mkdir specs
cat > specs/coding-style.spec.md <<EOF
---
id: my-coding-style
type: spec
tags: [go, style]
version: 1.0.0
---

# My Coding Style

- Functions MUST be documented
- ...
EOF

# index.yaml at repository root
version: "1"

packages:
  "@myorg/my-spec":
    name: "@myorg/my-spec"
    description: "My custom specifications"
    versions:
      - "1.0.0"
    latest: "1.0.0"

git add .
git commit -m "✨ feat: add my-spec package v1.0.0"
git remote add origin https://github.com/myorg/vibespec-registry.git
git push -u origin main

# .vibespec/vibespec.yaml
registries:
  - name: myorg
    type: git
    url: https://github.com/myorg/vibespec-registry.git

packages:
  - name: "@myorg/my-spec"
    version: "1.0.0"
    source: myorg

All packages MUST follow Semantic Versioning:

MAJOR.MINOR.PATCH

1.0.0  - Initial release
1.1.0  - Add new spec (backward compatible)
1.1.1  - Fix typo (patch)
2.0.0  - Breaking change (e.g., remove deprecated spec)

Support standard semver constraints:

packages:
  - name: "@vibespec/go-api"
    version: "^1.2.0"    # >=1.2.0, <2.0.0
  - name: "@vibespec/security"
    version: "~1.2.0"    # >=1.2.0, <1.3.0
  - name: "@myorg/custom"
    version: "1.0.0"     # Exact version

The index.yaml file at repository root helps CLI tools quickly discover packages without scanning the entire repository tree.

version: "1"

packages:
  "<package-name>":
    name: "<package-name>"
    description: "<description>"
    versions:
      - "1.0.0"
      - "1.1.0"
      - "1.2.0"
    latest: "1.2.0"
    tags: [tag1, tag2]        # optional
    deprecated: false          # optional
    replacement: ""            # optional, if deprecated

You can auto-generate index.yaml:

# Using provided script
./scripts/generate-index.sh

# Or manually
find packages -name "package.yaml" -exec cat {} \; | \
  yq eval-all 'group_by(.name) | ...' > index.yaml

# Set Git credential
git config --global url."https://${TOKEN}@github.com/".insteadOf "https://github.com/"

# Or use SSH
vibespec.yaml:
  registries:
    - name: private
      type: git
      url: git@github.com:mycompany/registry.git

# Use SSH URL for private repositories
registries:
  - name: company
    type: git
    url: git@github.com:mycompany/vibespec-registry.git

Ensure SSH keys are configured:

ssh-keygen -t ed25519 -C "your_email@example.com"
ssh-add ~/.ssh/id_ed25519
# Add public key to GitHub/GitLab

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

• Never modify published versions
• Create new version for any change
• Use Git tags to mark releases

packages/@vibespec/go-api/
├── 1.0.0/
├── 1.1.0/
├── 1.2.0/
├── 1.2.3/
└── CHANGELOG.md    # Document version changes

Use npm-style scopes for organization:

@vibespec/      - Official packages
@mycompany/     - Company-wide packages
@team/          - Team-specific packages
@personal/      - Personal packages

Update index.yaml when adding new versions:

# After adding version 1.3.0
git add packages/@vibespec/go-api/1.3.0/
# Update index.yaml
git add index.yaml
git commit -m "✨ feat: add go-api v1.3.0"
git push

Registry repositories are cached in:

~/.vibespec/cache/git-registries/
└── github_com_vibespec_registry/

Cache is refreshed every 5 minutes by default.

CLI uses git clone --depth 1 for faster downloads.

Always provide index.yaml for faster package discovery.

Feature	Git Registry	HTTP Registry
Deployment	None (use Git host)	Requires server
Cost	Free (GitHub, GitLab)	Hosting cost
Version Control	Native Git	Must implement
Access Control	Git permissions	API key
Offline Support	✅ Full	❌ No
Speed	Fast (local cache)	Network dependent
Search	Index file	Database query
Scalability	Git host's scale	Server dependent
Setup Complexity	Low	Medium

See packages/ directory or check index.yaml for the complete list.

• @vibespec/go-api - Go API development specs
• @vibespec/git-vcs - Git commit conventions
• @vibespec/react-web - React web development
• @vibespec/security - Security baseline
• More coming soon...

1. Fork this repository
2. Create your package in packages/@yourscope/packagename/version/
3. Update index.yaml
4. Submit a pull request

1. Create new version directory
2. Update index.yaml with new version and latest pointer
3. Submit pull request

• Documentation: https://vibespec.dev
• Issues: https://github.com/vibespec/registry/issues
• Discussions: https://github.com/vibespec/registry/discussions

This registry structure and tooling: MIT Individual packages: See each package's LICENSE file