ForgeMesh turns repository signals into a reviewable specialist-workforce configuration for the engineering tools a project uses.
ForgeMesh addresses a practical coordination problem: fixed AI-agent rosters do not reflect the languages, frameworks, infrastructure, tests or risks of the repository in front of them. This repository combines a canonical specialist-profile corpus with a TypeScript CLI that detects project signals, matches capabilities and generates platform-specific configuration.
The implemented product surface is a workforce setup and compilation tool. It does not claim to be a live autonomous engineering runtime; the generated profiles and handoff rules are inputs for supported AI coding environments.
ForgeMesh's current evidence is reproducible corpus and compiler verification, not a claim that its selected workforce is objectively optimal.
| Verifiable property | Current state | Reproduce / inspect |
|---|---|---|
| Canonical root specialist profiles | 340 across 22 category directories | npm run validate |
| Executable CLI catalog | 144 profiles across 22 domains | agents-profiles-cli/ |
| Root corpus validation | Checks counts, links, required handoff/anti-pattern sections, metadata, slugs, native outputs, and README consistency | npm run validate |
| CLI dependency/build boundary | Clean install, typecheck, and build are explicit | cd agents-profiles-cli && npm ci && npm run typecheck && npm run build |
| Project detection and matching | Implemented | node dist/bin/cli.js detect .. |
| Optimal team selection / downstream agent quality | Not established | requires future task benchmark |
These counts describe checked-in artifacts, not independent performance metrics. Native projections are not counted as additional specialists, and the root corpus and nested CLI catalog remain separate maintained layers.
ForgeMesh's technical signature is a repository-to-workforce compiler: it fingerprints a target codebase, maps detected capabilities and risks to specialist profiles, then emits configuration for supported AI coding environments.
Target repository
↓
Project fingerprint
↓
Capability matching
↓
Minimum-sufficient specialist set
↓
Platform-specific generation
↓
Human review
Distinguishing implementation choices:
- Evidence-driven detection — language, framework, data, infrastructure, CI, test, AI/ML, monitoring, mobile, embedded, and other repository signals feed selection.
- Minimum-sufficient composition — the matcher starts from orchestration/review foundations and adds specialists justified by detected needs.
- Canonical-to-native compilation — one specialist corpus can produce environment-specific configuration rather than maintaining unrelated copies by hand.
- Offline deterministic path — detection and catalog matching can run without an API key or model call.
- Atomic generation and rollback — setup can be reviewed locally and recovered when generation fails.
- Explicit provenance boundary — the repository preserves upstream lineage instead of presenting the inherited corpus as wholly original work.
- Implemented: detector, matcher, profile catalog, platform registry, generators, offline setup, and validation scripts.
- Verified by deterministic checks: corpus structure plus CLI install/typecheck/build lanes.
- Optional / experimental: model-assisted recommendations.
- Environment-dependent: network fetching and downstream coding-platform interpretation.
- Not claimed: autonomous repository mutation, optimal team composition, or production quality of downstream agents.
The root repository is a canonical profile corpus plus Bash/Python validation and generation scripts; it intentionally has no root npm dependency lockfile. The only npm dependency boundary is agents-profiles-cli, whose package-lock.json is authoritative for the TypeScript CLI and is validated with npm ci, typecheck and build in CI. The root validator and CLI validation do not require an API key.
From the repository root:
npm run validateThis runs the checked-in validate.sh audit. It checks source-file counts, README links, required handoff and anti-pattern sections, personality metadata, native-agent slug duplication, slug conventions, native output counts and README metadata consistency.
The executable TypeScript package lives in agents-profiles-cli:
cd agents-profiles-cli
npm ci
npm run typecheck
npm run build
node dist/bin/cli.js --help
node dist/bin/cli.js list
node dist/bin/cli.js detect ..To configure a target project without network fetches, run the built CLI from that project's path:
node /path/to/ForgeMesh/agents-profiles-cli/dist/bin/cli.js init /path/to/target --yes --offlineThe interactive init command can instead fetch specialist definitions from GitHub, select a target platform and generate the appropriate config. Deterministic project detection and catalog matching do not require an API key; model-assisted analysis is optional and requires the user's own compatible credentials.
- Evidence-driven matching: the detector scans repository signals such as languages, frameworks, package managers, databases, queues, cloud providers, Docker/Kubernetes/Terraform, CI/CD, test frameworks, mobile/embedded/game surfaces, AI/ML and monitoring.
- Minimum-sufficient composition: the matcher starts with orchestration/reviewer foundations, then adds language, framework, infrastructure, data and quality specialists justified by the detected project.
- Canonical-to-native compilation: the root corpus is the source of truth; generated native files are projections for OpenCode, Claude and GitHub Copilot. The CLI also knows how to emit configs for Cursor, Windsurf, Aider, Continue, Generic and custom providers.
- Offline and recoverable setup: the CLI supports the offline flag, atomic writes and rollback-on-failure behavior, so configuration generation can be reviewed locally and does not depend on a model call.
- Explicit responsibility contracts: profiles contain descriptions, categories, optional permission levels/tools, handoff protocols and anti-pattern guidance. A profile is a capability definition, not a running agent.
flowchart LR
R[Target repository] --> D[Project detector]
D --> F[DetectedProject fingerprint]
F --> M[Capability matcher]
C[Canonical profile corpus] --> M
M --> P[Selected specialist profiles]
P --> G[Platform generator]
G --> O[Config + native agent files]
O --> H[AI coding environment]
H --> E[Human review, tests and evidence]
A[Optional model-assisted analysis] -.-> M
There are two maintained layers:
- The root corpus contains 340 canonical source profiles across 22 category directories and generated native projections.
- The nested CLI package is versioned separately as forgemesh 0.2.1 and contains a curated 144-profile catalog across 22 domains, detector/matcher logic, platform registry, generators and the init, list and detect command surface.
The two counts are intentionally not combined: native projections are not additional profiles, and the CLI catalog is a separate executable package rather than a claim that every root profile is compiled into that release.
forgemesh init [directory]
1. detect project languages, frameworks, data and infrastructure signals
2. optionally apply model-assisted recommendations
3. choose OpenCode, Claude, Copilot, Cursor, Windsurf, Aider,
Continue, Generic or a custom provider
4. select minimal, standard or complete specialist depth
5. resolve profiles locally or fetch them when online
6. generate platform config and specialist files
Useful commands:
| Command | Purpose |
|---|---|
| forgemesh init [dir] | Interactive project-aware setup |
| forgemesh init [dir] --yes | Non-interactive minimal setup |
| forgemesh init [dir] --yes --offline | Local/offline setup without GitHub fetches |
| forgemesh detect [dir] | Print the detected system fingerprint |
| forgemesh list | Show supported platform outputs |
business-analysis/ ... testing-quality/ Canonical profile categories
native-agents/ Generated platform projections
native-agents/generate.py Root corpus-to-native generator
validate.sh Corpus and metadata audit
agents-profiles-cli/src/cli.ts CLI command and help surface
agents-profiles-cli/src/detectors/ Repository fingerprint detection
agents-profiles-cli/src/generators/ Profile selection and output generation
agents-profiles-cli/src/platforms/ Built-in platform registry
agents-profiles-cli/src/commands/ Interactive and non-interactive setup
agents-profiles-cli/templates/ Platform configuration templates
The root validation script verifies repository consistency; it does not prove that every profile is technically correct, that a selected workforce is optimal, or that a downstream AI platform will execute generated configuration without adaptation.
The CLI package has build and typecheck lanes but no claim here of a complete end-to-end test suite. Network fetching, optional model-assisted analysis and downstream platform behavior remain environment-dependent. Review generated diffs before committing them to a target project.
The project is best evaluated as a repository-intelligence and configuration-compilation tool: it detects signals, selects documented capabilities and generates handoff/configuration artifacts. It does not itself provide provider sessions, execute repository mutations or establish production readiness for a configured AI environment.
The root package.json still identifies the upstream repository as CrimsonDevil333333/agents-profiles, and the root LICENSE retains its 2024 MIT copyright notice. The nested CLI declares MIT licensing and the ForgeMesh repository as its package home.
This README preserves that lineage rather than presenting the entire corpus as wholly original work. Preserve the retained notice and review contribution provenance before redistributing or materially rebranding the source corpus.
Jason Lee
GitHub: @Masterleeaus