Monorepo Support

Hierarchical standards and brownfield detection for multi-module projects

First-Class Monorepo Support

FIRE is designed from the ground up for real-world projects, including complex monorepo architectures with multiple tech stacks.

Hierarchical Standards

How It Works

Standards follow a hierarchical inheritance model:

1. Root standards define project-wide defaults
2. Module standards override specific files when needed
3. Constitution is special—always inherited, never overridden

Project Structure

project/
├── .specs-fire/
│   ├── state.yaml                 # Single source of truth
│   └── standards/
│       ├── constitution.md        # Universal policies (ALWAYS inherited)
│       ├── tech-stack.md          # Default: Node.js, TypeScript
│       ├── coding-standards.md    # Default coding conventions
│       └── testing-standards.md   # Default test patterns
│
├── packages/api/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md      # Override: Go, Echo, golangci-lint
│
├── packages/web/
│   └── .specs-fire/
│       └── standards/
│           └── tech-stack.md      # Override: React, Vite, Tailwind
│
└── services/ml/
    └── .specs-fire/
        └── standards/
            └── tech-stack.md      # Override: Python, FastAPI, ruff

Resolution Rules

The Constitution

The constitution contains universal policies that apply everywhere:

# Project Constitution

## Git Workflow
- All changes via pull request
- Require 1 approval before merge
- Squash merge to main

## Security
- No secrets in code
- Environment variables for configuration
- Dependency scanning enabled

## CI/CD
- All PRs must pass CI
- Deploy to staging on merge to main
- Manual promotion to production

## Quality
- All new code must have tests
- Maintain >80% coverage on critical paths

Why Constitution is Special

• Ensures consistent policies across all modules
• Prevents “rogue” modules with different rules
• Simplifies onboarding—one place for universal rules
• AI always knows where to find project-wide policies

Tech Stack Detection

FIRE doesn’t hardcode tech stacks—it detects them:

Quick Scan (2-5 minutes)

Pattern-based detection:

• Package files: package.json, go.mod, requirements.txt, Cargo.toml
• Lock files: package-lock.json, yarn.lock, pnpm-lock.yaml
• Config files: tsconfig.json, .eslintrc, pyproject.toml
• Framework markers: next.config.js, vite.config.ts, main.go

Deep Scan (10-30 minutes)

Code analysis:

• Import patterns and dependencies
• Folder structure conventions
• Test framework usage
• Build tool configuration
• Integration patterns (APIs, databases)

Generated Tech Stack

After scanning, FIRE generates a tech-stack.md:

# Tech Stack

## Language
- TypeScript 5.x
- Node.js 20 LTS

## Framework
- Express.js for API
- React 18 for frontend

## Database
- PostgreSQL 15
- Prisma ORM

## Testing
- Vitest for unit tests
- Playwright for E2E

## Tooling
- ESLint + Prettier
- pnpm workspaces
- Turborepo for builds

Brownfield Support

FIRE treats existing codebases as first-class citizens.

Brownfield Rules

Standards Inference

For brownfield projects, FIRE infers standards from existing code:

Inferred vs Prescribed

Monorepo Detection

FIRE automatically detects monorepo structures:

Detection Signals

Workspace Analysis

After detection, FIRE maps the workspace:

workspace:
  type: brownfield
  structure: monorepo
  parts:
    - name: packages/api
      tech: go
      framework: echo
    - name: packages/web
      tech: typescript
      framework: react
    - name: services/ml
      tech: python
      framework: fastapi
  integrations:
    - type: database
      provider: postgresql
    - type: cache
      provider: redis
  key_files:
    - packages/api/main.go
    - packages/web/src/App.tsx
    - services/ml/main.py

Working with Modules

Targeting a Module

When creating work items, specify the target module:

work_item:
  id: add-user-endpoint
  module: packages/api  # Target specific module
  title: Add user CRUD endpoint

FIRE will:

1. Load module-specific standards
2. Respect module’s tech stack
3. Follow module’s conventions

Cross-Module Work

For work spanning multiple modules:

work_item:
  id: user-feature
  modules:
    - packages/api      # Backend changes
    - packages/web      # Frontend changes
  title: Add user management feature
  complexity: high      # Cross-module = higher complexity
  mode: validate        # Recommend Validate mode

Best Practices

When to Override Standards

Keeping Standards in Sync

• Review root standards periodically
• Update constitution when policies change
• Keep module overrides minimal
• Document why overrides exist

Module-Specific Conventions

Add context to module standards:

# Tech Stack - packages/api

## Why Go?
Selected for API module due to:
- High performance requirements
- Strong typing for data validation
- Excellent concurrency support

## Migration from Node
Originally Node.js, migrated in Q3 2024 for performance.
Some utility code still in TypeScript during transition.

Initialization Workflow

npx specsmd@latest install