Skip to content

Onboarding Guide

NON-NORMATIVE. This is an operational guide. Normative rules are in docs/governance/morphism-kernel.md.

Welcome to the Morphism Systems monorepo. This guide walks you through setup, the governance reading order, and your first PR checklist.

1. Clone and Setup

# Clone the repository
git clone https://github.com/morphism-systems/morphism.git
cd morphism-systems

# Install git hooks
bash scripts/install-hooks.sh

# Verify hooks are installed
ls .githooks/

2. TypeScript Setup

# Install dependencies
npm install

# Build all workspaces
npx turbo build

# Run linters and type checks
npx turbo typecheck
npx turbo lint

# Run tests
npx turbo test

3. Python Setup

# Install Python core with dev dependencies
pip install -e ".[dev]"

# Run linters and type checks
ruff check src/ tests/
mypy src/

# Run tests
pytest tests/

4. Governance Reading Order

Read these documents in order before making structural changes:

  1. AGENTS.md — Root governance rules and protocol
  2. SSOT.md — Scope, authority, and configuration map
  3. GUIDELINES.md — Naming, git, code style conventions (tenet format)
  4. docs/governance/MORPHISM.md — MORPHISM Framework with operational tenets and enforcement details
  5. docs/operations/handoff-and-integration.md — Integration checklist and Sentry setup
  6. docs/operations/deferred-work.md — Deferred work backlog

5. Key Directories

Directory Purpose
apps/morphism/ Next.js SaaS application
packages/shared/ Shared TypeScript utilities (@morphism-systems/shared)
src/morphism/ Python core — category theory engine + CLI
docs/ Documentation (MkDocs site)
scripts/ Governance and automation scripts
.morphism/ Consumer governance config, agents, hooks, schemas
.githooks/ Git hook shims (delegates to .morphism/hooks/ and policy scripts)

6. Branching and Commits

  • Branch naming: feat/description, fix/description, docs/description, etc.
  • Commit messages: type(scope): subject — see commit grammar
  • Pull requests: Required for main. Squash merge preferred.
  • Ticket references: Include MOR-<number> in commit footer when applicable.

7. First-PR Checklist

Before submitting your first PR:

  • [ ] Hooks installed (bash scripts/install-hooks.sh)
  • [ ] Branch name follows convention (feat/..., fix/..., etc.)
  • [ ] Commit messages follow grammar (type(scope): subject)
  • [ ] TypeScript checks pass (npx turbo typecheck && npx turbo lint && npx turbo test)
  • [ ] Python checks pass (ruff check src/ tests/ && mypy src/ && pytest tests/)
  • [ ] No secrets or credentials in staged files
  • [ ] New features include tests
  • [ ] Documentation updated if applicable
  • [ ] If runtime/code surfaces changed, run python scripts/docs_contract.py --check --working-tree
  • [ ] If release behavior changed, update docs/release-notes/ and the coupled authoritative docs in the same branch
  • [ ] Read the governance docs listed in section 4

8. Team Contacts

Team Responsibility Contact
@platform-team CI/CD, hooks, SSOT, infrastructure Platform channel
@security-team Secret scanning, vulnerability management Security channel
@sre-oncall Incident response, runbooks, monitoring SRE channel

9. Useful Commands

# Run all validations
python scripts/policy_check.py --mode ci --explain

# Check for governance drift
python scripts/drift_detector.py

# Check SSOT integrity
python scripts/ssot_verify.py

# Check docs for orphans/broken links
python scripts/docs_graph.py --check

# Check docs contract metadata and runtime-doc coupling
python scripts/docs_contract.py --check --working-tree

# Check repo maturity score
python scripts/maturity_score.py