Getting Started: Contributors

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

External users install products with npm (see Engineering Leaders or Engineers). This page is for contributors who work 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 tests and development:

just synthetic

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

Other generation modes:

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

Run checks

Run the format and lint checks, then the unit tests, before you commit:

bun run check
bun run test

bun run check runs format, lint, jsdoc, invariants, context, and wiki sequentially so you can spot failures easily. bun run test runs unit tests (bun test) separately so test output does not bury check failures.

To fix format and lint issues automatically:

bun run check:fix

Understand the structure

products/       Products that turn the standard into tooling
libraries/      Shared libraries (libskill, libdoc, libbridge, etc.)
services/       gRPC microservices supervised by fit-rc
data/           Generated and standard data
config/         Service and tool configuration
specs/          Feature specifications and plans
websites/       Public site sources (websites/fit/, websites/kata/, …)

The products tree holds these

ten

products:

• gear
• gemba
• guide
• jidoka
• kata
• landmark
• map
• outpost
• pathway
• summit

The services tree holds these gRPC microservices:

• bridge
• embedding
• ghbridge
• ghserver
• ghuser
• graph
• map
• mcp
• msbridge
• oauth
• oidc
• pathway
• span
• tenancy
• vector

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. Landmark surfaces engineering-system signals from Map's activity layer. Kata orchestrates an autonomous agent team that ships and improves itself. Gear is a meta-package that re-exports all service and library CLIs as dependencies.

Libraries provide shared logic that follows OO+DI patterns. Classes accept dependencies through constructors. Factory functions wire real implementations. Tests inject mocks directly.

Services are gRPC microservices that fit-rc supervises. Start them with bunx fit-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 and a gitleaks secret scan)
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