Shipshape

Shipshape checks Lucas's engineering practices across his repositories. A GitHub App inventories the repositories it can access, reads a versioned practice catalog, evaluates bounded checks at each default-branch commit, and stores the results for the dashboard and MCP.

The service covers personal and organization repositories, including private repositories. The central Auth Worker verifies the linked GitHub identity; all repository reads use installation tokens. Results preserve pass, fail, unknown, and not_applicable states.

Connect

codex mcp add shipshape \
  --url https://shipshape-mcp.aranlucas.workers.dev/mcp \
  --oauth-client-registration auto

The MCP tools are practices_overview, repo_practices, and practice_detail. The browser dashboard is available at /app. Both authenticate through Auth; connect GitHub on its account page. Shipshape validates resource-bound shipshape:access tokens and the configured numeric GitHub owner ID. See the migration guide for server setup and rollout.

Related MCP server: ProofScope

Practice catalog

Practices live in the private aranlucas/practices catalog repository. Each practice has a strict practice.yml definition and may include canonical files and agent instructions. Checks cover repository files, JSON/YAML paths, dependencies, repository settings, branch protection, and workflow security.

Practice appliesTo.include and appliesTo.exclude selectors accept case-insensitive * and ? globs. Bare patterns such as legacy-* match repository names across owners; patterns containing /, such as aranlucas/agents-mobile or octo/*, match the full owner/repository name. Exclusions take precedence over inclusions.

The CI practice includes ci-required-checks: jobs in .github/workflows/ci.yml must be required status checks on the default branch. It uses each job's name or job ID and allows additional required checks. Dynamic names, matrix jobs, reusable workflows and unreadable protection settings remain unknown. Shipshape reports missing requirements and provides remediation instructions without changing repository settings. Deploy evaluator support before adopting the updated seed in the separate live catalog.

The CI practice also includes ci-test-script: the root package.json must declare a non-empty scripts.test, and .github/workflows/ci.yml must invoke it through a package-manager script command or a simple alias. Parallel steps are supported; conditional, indirect, or failure-ignoring execution needs review.

The vitest-test-script check requires every tracked package.json, including nested packages, to declare a test script that runs Vitest (for example, "test": "vitest run"). It reads manifests at the evaluated commit without executing scripts. Unreadable files, incomplete inventories, and indirect or complex commands require review and remain unknown.

The pr-workflow-efficiency check requires PR workflows to cancel superseded runs using stable concurrency groups, start when a PR becomes ready for review, and skip draft work at every job. The converted_to_draft event is optional. Path-filter cleanup, reusable workflow internals, and complex expressions remain unknown for review. The seed includes remediation instructions; deploy evaluator support before adopting it in the separate live catalog.

The required-package-scripts check also requires non-empty lint, format, and build scripts in every tracked package.json. Missing entries and obvious placeholders fail. It checks declarations without running commands; unreadable manifests and incomplete inventories remain unknown unless a known failure exists.

The husky-lint-staged check reads package.json, .husky/pre-commit, and recognized root lint-staged configuration files. It checks local dependencies, Husky initialization through prepare or postinstall, nonempty inline or JSON/YAML tasks, and a hook invocation that preserves lint failures. Common npm, pnpm, Yarn and Bun commands and bounded package-script aliases are supported. It never executes repository commands. Custom installers, shell preambles, CLI config/cwd/diff selectors, ambiguous configuration and JS/TS tasks require review and remain unknown. Task execution and machine-local Git settings are outside this static check.

The portless-local-dev and cloudflare-cf-cli seed practices capture recurring requests for local development tooling. Their evidence, existing related rules, and adoption boundaries are recorded in docs/recurring-preferences.md. Deploy evaluator support before adopting the definitions in the separate live catalog.

The dashboard and API contract are documented in docs/architecture.md; the TypeScript response source of truth is src/api/contract.ts. Setup instructions for the GitHub App, D1 database, queue, and catalog repository are in docs/setup.md.

Develop

pnpm install --frozen-lockfile
cp .dev.vars.example .dev.vars
pnpm types
pnpm check
pnpm dev

The dashboard is a Preact bundle in src/ui. Work on it without GitHub credentials using fixture data in the API contract's shape:

pnpm ui:dev   # http://localhost:5200/app/

pnpm ui:build writes the bundle to public/app/, which the Worker serves as static assets; pnpm build, pnpm dry-run, and pnpm preview run it first. Run it once before pnpm dev so the Worker can serve the dashboard shell.

Use pnpm release to build, apply D1 migrations, and deploy production. Workers Builds runs pnpm build followed by pnpm release:ci to reuse the artifact. pnpm run deploy uploads an existing build without applying migrations; pnpm dry-run builds and validates without database writes or upload. See the deployment setup for the Workers Builds commands and deployment options.

See SECURITY.md for the security boundary and reporting instructions.

Architecture

flowchart LR
  GitHub[GitHub App] --> Inventory[Inventory + installation tokens]
  Catalog[Practice catalog repository] --> Queue[Evaluation queue]
  Inventory --> Queue
  Queue --> Engine[Practice check engine]
  Engine --> DB[(D1 results)]
  DB --> API[Dashboard API]
  DB --> MCP[MCP tools]

• src/github/app.ts creates App and installation clients.

• src/inventory/sync.ts refreshes every installation's repositories.

• src/practices/ parses the catalog, reads bounded repository snapshots, and evaluates checks.

• src/queue.ts and src/scheduled.ts trigger evaluation after pushes and on the daily sweep.

• src/api/routes.ts and src/mcp.ts expose the shared response contract.

Local checks

pnpm check runs generated Worker types, typechecking, linting, formatting, the node and Worker test projects, and a Cloudflare dry run. Repository reads are bounded and no repository code is cloned, executed, or mutated by the Worker.