@eonium/compass-business-sherpa

Compass Business Sherpa scaffold generator for durable business truth.

This package initializes the repo-local Business Sherpa documentation surface under .eonium/compass/sherpa/business/. Business Sherpa records product behaviour that should survive framework, provider, frontend, backend and migration changes: workflows, lifecycle rules, permissions, domain concepts, calculations, validation rules, side effects and data dependencies.

What this package does

initBusinessSherpa generates purpose-clear documentation scaffolds for business truth. The generated files are intentionally mostly empty until a human or agent fills them with verified product behaviour.

Generated files:

.eonium/compass/sherpa/business/LLMsherpa.md
.eonium/compass/sherpa/business/domain-glossary.md
.eonium/compass/sherpa/business/workflow-map.md
.eonium/compass/sherpa/business/lifecycle-rules.md
.eonium/compass/sherpa/business/permissions.md
.eonium/compass/sherpa/business/data-dependencies.md
.eonium/compass/sherpa/business/migration-survival-rules.md
.eonium/compass/sherpa/business/decisions.md
.eonium/compass/sherpa/business/changelog.md

Write behaviour

The initializer uses the shared Compass scaffold writer from @eonium/compass-core.

• If no mode is supplied, initialization defaults to dry-run and reports a warning.
• Dry-run mode reports the files that would be created or updated without writing .eonium files.
• Write mode creates missing Business Sherpa files.
• Existing files are preserved by default.
• Already-current files are skipped.
• Existing files are updated only when force: true is supplied.
• The returned result includes files, scaffoldResults, changed, dryRun, force and the shared Compass change report.
• The returned report distinguishes created, updated, skipped, warned and errored files.

Package boundary

This package creates Business Sherpa documentation scaffolds only.

Business Sherpa should record durable business truth such as:

• domain language and product concepts;
• user journeys and workflows;
• lifecycle states, transitions and timing rules;
• roles, permissions, access expectations and trust boundaries;
• calculations, eligibility rules and validation rules;
• side effects, notifications and operational dependencies;
• business data dependencies, ownership and sensitivity expectations;
• behaviour that must survive framework, provider, frontend, backend or platform changes.

It does not:

• parse FlutterFlow exports;
• inspect generated FlutterFlow source code;
• perform source-code archaeology;
• store source-to-target migration maps;
• generate frontend routes, components, state controllers or app services;
• own frontend architecture, design-system, screen-map or route-map truth;
• own backend implementation architecture, provider configuration or DB schema internals;
• own FF Migrator prompt packs, graph files, sprint plans, step plans or migration logs;
• call AI providers or require BYOK configuration.

Migration-specific implementation notes, porting tactics, prompt text, active sprint scope and step instructions belong in the migration surface or Create artifacts, not in Business Sherpa. Frontend implementation truth belongs in Frontend Sherpa. Backend implementation truth belongs in Backend Sherpa when present.

Backend-optional support

Business Sherpa supports projects with or without backend Sherpa.

• If no backend repo or backend Sherpa exists, record verified business behaviour and mark backend ownership or enforcement as unknown.
• If a backend repo exists but has no Sherpa, summarize only product-relevant behaviour verified from the available evidence.
• If backend Sherpa exists, link to backend Sherpa for implementation details instead of copying backend architecture into Business Sherpa.
• If Business Sherpa and Backend Sherpa disagree, record the mismatch as an uncertainty or gap rather than silently resolving it.

API

import { initBusinessSherpa } from "@eonium/compass-business-sherpa";

const dryRun = initBusinessSherpa({ repoRoot: process.cwd() });
const write = initBusinessSherpa({ repoRoot: process.cwd(), mode: "write" });
const forced = initBusinessSherpa({ repoRoot: process.cwd(), mode: "write", force: true });

initBusinessSherpa() returns the generated file descriptors, per-file scaffold results, a boolean changed value and a Compass change report suitable for CLI orchestration.

Non-goals

This package is not a migration engine, parser, AI integration, backend inspector, frontend generator or app-code generator. It only creates the Business Sherpa scaffold that future humans and agents can fill with verified durable business truth.