@digitalist/conventions

Organizational conventions for Digitalist projects, optimized for GSD (Get Shit Done) integration.

Installation

From npm (recommended)

# Using pnpm
pnpm add -g @digitalist/conventions

# Using npm
npm install -g @digitalist/conventions

From GitHub (development)

pnpm add -g github:digitalist-se/digitalist-conventions

Run the install script

pnpm users: pnpm blocks postinstall scripts by default for security. Run manually:

digitalist-conventions update

npm users: The postinstall script runs automatically.

Verify installation

digitalist-conventions verify

Expected output:

[OK] Conventions installed at ~/.claude/digitalist/conventions/
[OK] GSD symlink exists -> ~/.claude/digitalist/conventions/index.md
[OK] Version: 1.0.0

Project Setup

Initialize a project with local conventions

cd your-project
digitalist-conventions init

This creates .planning/CONVENTIONS.local.md where you can add project-specific rules that extend or override the organization conventions.

Example workflow

# 1. Install conventions (once per machine)
pnpm add -g @digitalist/conventions
digitalist-conventions update  # Required for pnpm users

# 2. Initialize your GSD project
cd my-project
digitalist-conventions init

# 3. Edit project-specific conventions (optional)
# Edit .planning/CONVENTIONS.local.md

# 4. Run GSD - agents will auto-load conventions
/gsd:plan-phase 1

CLI Commands

| Command | Description | |---------|-------------| | digitalist-conventions init | Create .planning/CONVENTIONS.local.md in current project | | digitalist-conventions init --force | Overwrite existing local conventions | | digitalist-conventions verify | Check that conventions are installed correctly | | digitalist-conventions info | Show installation paths and version | | digitalist-conventions update | Re-sync conventions from package | | digitalist-conventions help | Show help message |

How it works

Three-layer convention system

┌─────────────────────────────────────────────────────────┐
│ Layer 3: Project-specific                               │
│ .planning/CONVENTIONS.local.md                          │
│ → Override/extend for this project only                 │
└─────────────────────────────────────────────────────────┘
                          ↑ extends
┌─────────────────────────────────────────────────────────┐
│ Layer 2: Organization Conventions                       │
│ ~/.claude/digitalist/conventions/                       │
│ → Shared across all Digitalist projects                 │
└─────────────────────────────────────────────────────────┘
                          ↑ extends
┌─────────────────────────────────────────────────────────┐
│ Layer 1: GSD Core                                       │
│ ~/.claude/get-shit-done/                                │
│ → Base GSD system                                       │
└─────────────────────────────────────────────────────────┘

GSD Integration

The install script creates a symlink:

~/.claude/get-shit-done/references/org-conventions.md
    → ~/.claude/digitalist/conventions/index.md

GSD agents (planner, executor, researcher) automatically load files from the references/ directory, so your conventions are available without any additional configuration.

Convention Files

| File | Description | |------|-------------| | index.md | Main manifest with summary of all conventions | | stack.md | Required tech stack (Node, React, Tailwind, etc.) | | architecture.md | Three-layer architecture patterns | | security.md | Security requirements (validation, rate limiting, etc.) | | testing.md | Testing strategy (Vitest, Playwright, etc.) | | commits.md | Commit message conventions | | forbidden.md | Patterns that are NOT allowed |

Updating Conventions

When conventions are updated:

# Update the package
pnpm update -g @digitalist/conventions

# Re-sync conventions (required for pnpm users)
digitalist-conventions update

Customizing for Your Organization

1. Fork this repo
2. Edit files in conventions/ to match your standards
3. Update package.json with your org name
4. Install from your fork:

   pnpm add -g github:your-org/your-conventions-repo

Troubleshooting

"command not found: digitalist-conventions"

The CLI binary isn't in your PATH. Try:

# Check where pnpm installed it
pnpm bin -g

# Add to PATH if needed
export PATH="$HOME/Library/pnpm:$PATH"

"GSD symlink missing"

GSD might not be installed, or was installed after conventions. Re-run:

digitalist-conventions update

Conventions not loading in GSD

Verify the symlink exists:

ls -la ~/.claude/get-shit-done/references/org-conventions.md

If missing, run the install script again.

License

MIT