Contributing to Shep

May 19, 2026 · View on GitHub

Thanks for being here. Shep is an AI-native SDLC platform — and one of its native abilities is helping itself. This guide gets you from a fresh clone to a merged PR, optionally using Shep's own agents along the way.

If you only have a few minutes, skim 30-Second Setup and Lanes, then pick something from GOOD_FIRST_ISSUES.md.

30-Second Setup

# 1. Clone
git clone https://github.com/shep-ai/shep.git && cd shep

# 2. Install
pnpm install

# 3. Verify your environment is contributor-ready
pnpm dev:cli doctor

shep doctor checks Node/pnpm/git/gh versions, available agent CLIs (Claude/Cursor/Gemini), .env presence, working-tree state, migration status, TypeSpec freshness, and DI graph health. It exits non-zero on any blocker and prints a fixHint for everything it can suggest.

If shep doctor is green, you're ready to ship.

# 4. (optional) build + run tests
pnpm build
pnpm test:unit

Lanes

Every issue, PR, and contributor in Shep belongs to a lane — the part of the system you're touching. Lanes are real TypeSpec enum values (ContributorLane), not just labels: they drive issue grooming, PR routing, and the contributor leaderboard.

LaneWhat lives hereGood if you like…
docsREADME.md, CONTRIBUTING.md, docs/, JSDoc, LESSONS.mdWriting for humans; clarifying non-obvious behavior
agentstsp/agents/, application/use-cases/agents/, infrastructure/agents/, promptsLLMs, prompts, supervisor flow, agent-agnostic plumbing
uisrc/presentation/web/, Storybook stories, Playwright e2eReact, Next.js, dashboards, visual polish
clisrc/presentation/cli/, Commander commands, terminal UXCommander, terminal UX, structured output
infrainfrastructure/, migrations, DI, persistence, GitHub plumbingSQLite, ports/adapters, queues, schedulers

Issue templates ask you to pick a lane and a difficulty (goodFirst | easy | medium | hard). The contributor-onboarding agent uses both to suggest reviewers and group monthly recaps.

Contributor Ladder

Shep recognises four levels. Movement is tracked automatically by award-recognition on every merged PR.

LevelHow to get hereWhat it unlocks
UserRun npx @shepai/cli onceThe product. Filing issues. Discord access.
ContributorOne merged PRA row in .all-contributorsrc, the README contributors block, and the monthly recap.
CoreFive merged PRs across at least two lanes, plus three reviews of others' PRsTriage rights on labels, PR review assignment, vote on roadmap entries.
MaintainerSustained Core activity (≥ 3 months), demonstrated judgment on architectural calls, invitation by current maintainersMerge rights, release ownership, supervisor-policy authority.

Levels are public-by-construction: only data already on your GitHub profile (login, avatar, public PR/issue history) is used.

Contributing to Shep with Shep

This is the dogfooding loop. Use Shep's own agents to land your PR.

1. Pick an issue, or have Shep groom one

Browse GOOD_FIRST_ISSUES.md, or take any open issue and run:

pnpm dev:cli contributors groom-issue --number 1234

The contributor-onboarding agent fetches the issue, classifies its lane (rules-first, agent fallback when ambiguous), proposes acceptance criteria as a markdown checklist, and suggests labels. Nothing is applied until the supervisor approval gate clears.

2. Spin up a worktree and start work

shep feat new "fix: <description from the groomed issue>"

Shep creates an isolated git worktree, branches from main, and hands the prompt to your agent of choice (Claude / Cursor / Gemini). You stay in your editor; Shep handles the boring parts.

3. Let Shep commit, push, and open the PR

shep feat new "..." --push --pr

The agent commits in conventional-commit format, pushes the branch, and opens a draft PR. CI runs your tests and security scans; if anything fails, Shep retries up to three times before pausing for human input.

4. First merge → automatic recognition

When your PR merges, welcome-first-time-contributor posts a welcome comment (gated on supervisor approval), award-recognition adds you to .all-contributorsrc and the README contributors block, and your name appears in the next monthly recap published to recaps/YYYY-MM.md, GitHub Discussions, and Discord.

You graduated from User to Contributor. No bot install required — Shep did it.

Quick Contributions (no spec workflow needed)

For typo fixes, doc clarifications, single-file bug fixes, or dependency bumps, skip the spec workflow:

  1. Fork → branch from main (git checkout -b fix/your-fix-name)
  2. Make the change
  3. pnpm dev:cli doctor (still green?)
  4. pnpm test:unit && pnpm lint
  5. Commit using Conventional Commits — type and scope are enforced (fix(docs): ..., feat(cli): ...)
  6. Open a PR against main using the PR template

Full Feature Development

For new features, architectural changes, and significant enhancements we use the spec-driven workflow.

/shep-kit:new-feature → /shep-kit:research → /shep-kit:plan → /shep-kit:implement → /shep-kit:commit-pr

This produces a versioned spec under specs/NNN-feature-name/ with five YAML artifacts (spec, research, plan, tasks, feature). Edit the YAML — markdown is auto-generated. See docs/development/spec-driven-workflow.md for the full flow.

Coding Standards

Before opening a PR, verify locally:

pnpm lint && pnpm typecheck && pnpm test:unit && pnpm test:int && pnpm build

CI mirrors this sequence; passing locally means CI passes.

Architecture

Shep follows Clean Architecture with four layers. Dependencies point inward.

  • domain/ — TypeSpec-generated types and pure business logic. No external deps.
  • application/ — Use cases and output port interfaces. No infrastructure imports.
  • infrastructure/ — Adapters: SQLite, agents, GitHub, file system, Discord. Behind ports.
  • presentation/ — CLI, TUI, web. Calls only use cases.

If you find yourself importing from infrastructure/ outside infrastructure/, define a port in application/ports/output/ instead. See docs/architecture/clean-architecture.md.

TDD is mandatory

Every use case lands RED-first: a failing test that describes intent, then the smallest code that turns it green, then refactor. See docs/development/tdd-guide.md.

TypeSpec-first

Domain models live in tsp/. Run pnpm tsp:compile to regenerate packages/core/src/domain/generated/output.ts. Never edit the generated file. See docs/development/typespec-guide.md.

File length

No new file over ~300 lines of focused code. If you need to add to a long file, refactor it first.

Storybook is mandatory for web components

Every component under src/presentation/web/components/ ships with a colocated .stories.tsx covering Default, Loading, Empty, and Error states. PRs without stories are rejected.

Commit Format

Conventional Commits — strict.

<type>(<scope>): <subject>
  • types: feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert
  • scopes: specs | shep-kit | cli | tui | web | api | domain | agents | deployment | tsp | deps | config | dx | release | ci
  • subject: lowercase, ≤ 72 chars, imperative ("add", "fix", "remove")

Use feat or fix for anything users will see — those trigger releases. style, refactor, chore, test, ci, build, docs do not.

PR Process

  1. Open against main using the PR template
  2. Fill in What, Why, Screenshots / Recording (UI changes), Testing, Checklist
  3. CI must be green (lint, typecheck, unit, integration, build, Storybook)
  4. A maintainer reviews; small PRs get reviewed faster
  5. Squash merge; semantic-release publishes on feat/fix to main

Reporting Issues

Use the issue templates — they collect lane, difficulty, and acceptance criteria so the grooming agent can pick up where you left off.

Search existing issues first. Include shep doctor output for environment bugs.

Questions?

Maintaining This Document

Update CONTRIBUTING.md when:

  • The contribution flow changes (new commands, new gates, new lanes)
  • A lane is added, renamed, or removed
  • The contributor ladder criteria change
  • A new top-level doc joins the navigation block

Related docs: