Getting Started: Contributors

Set up the Forward Impact monorepo for development. This guide covers installation, data generation, and running the quality checks.

External users install products via npm (see Engineering Leaders or Engineers). This page is for contributors working on the monorepo itself.

Prerequisites

• Bun 1.2+
• just (command runner)

Clone and install

git clone https://github.com/forwardimpact/monorepo.git
cd monorepo
bun install
just quickstart

The quickstart target bootstraps environment files, generates data, runs codegen, and processes resources.

Generate synthetic data

The monorepo includes a synthetic data pipeline for testing and development:

just synthetic

This uses cached prose from data/synthetic/prose-cache.json and requires no LLM access. It produces agent-aligned engineering standard definitions, organizational documents, and activity data that the products consume during development and testing.

Other generation modes:

just synthetic-update     # Regenerate prose via LLM and update the cache

Run checks

Run formatting and linting, then unit tests, before committing:

bun run check
bun run test

bun run check runs format, lint, jsdoc, harness, and context sequentially so failures are easy to spot. bun run test runs unit tests (bun test) separately so test output does not bury check failures.

To auto-fix formatting and lint issues:

bun run check:fix

Understand the structure

products/       Seven products (map, pathway, outpost, guide, summit, landmark, gear)
libraries/      Shared libraries (libskill, libui, libdoc, etc.)
services/       gRPC microservices (trace, vector, graph, pathway, map, mcp)
data/           Generated and standard data
config/         Service and tool configuration
specs/          Feature specifications and plans
websites/       Public site sources (websites/fit/, websites/kata/, …)

Products answer specific questions for specific users. Map defines what good engineering looks like. Pathway renders agent-aligned engineering standards. Outpost manages personal knowledge. Guide interprets artifacts. Summit models team capability.

Libraries provide shared logic following OO+DI patterns — classes accept dependencies through constructors, factory functions wire real implementations, tests inject mocks directly.

Services are gRPC microservices supervised by fit-rc. Start them with just rc-start.

Development workflow

1. Create a branch from main
2. Make your changes
3. Run bun run check and bun run test
4. Run just audit (npm audit + gitleaks secret scanning)
5. Commit and push

Commit messages follow conventional format: type(scope): subject. Types include feat, fix, refactor, docs, test, chore, and spec. Scope is the package name (e.g., map, libskill, pathway). Add ! after scope for breaking changes.

What's next