# njm04/engineering-agents architecture

> Architecture diagram of the GitHub repository njm04/engineering-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/njm04/engineering-agents
- Repository: https://github.com/njm04/engineering-agents

## Overview

engineering-agents is a reusable toolkit for distributing engineering-agent instructions, standards, and platform-specific agent definitions into other repositories. The main workflow is install or sync: a user selects or detects an adapter, then the deployment engine prepares and writes the package-owned files while preserving protected project files. Separate capabilities generate this repository’s Codex agents and validate its canonical content and generated output. The graph follows the README and sampled scripts; unsampled content is represented at its exact directory level.

Main entry points: [`scripts/deployment.ts`](https://github.com/njm04/engineering-agents/blob/main/scripts/deployment.ts) (Deployment engine), [`scripts/validate.ts`](https://github.com/njm04/engineering-agents/blob/main/scripts/validate.ts) (Repository validation), [`scripts/setup-repo.ts`](https://github.com/njm04/engineering-agents/blob/main/scripts/setup-repo.ts) (Local Codex setup), [`scripts/install.ts`](https://github.com/njm04/engineering-agents/blob/main/scripts/install.ts) (Install command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_content["Reusable guidance"]
  node_roles["Agent roles"]
  node_standards["Engineering standards"]
  node_templates["Base templates"]
end

subgraph group_platform["Platform adapters"]
  node_codex["Codex templates"]
  node_copilot["Copilot templates"]
end

subgraph group_deploy["Deployment"]
  node_install["Install command<br/>[install.ts]"]
  node_sync["Sync command<br/>[sync.ts]"]
  node_engine["Deployment engine<br/>[deployment.ts]"]
  node_installed["Installed guidance and agents"]
end

subgraph group_maintenance["Repository maintenance"]
  node_setup["Local Codex setup<br/>[setup-repo.ts]"]
  node_localagents["Generated Codex agents<br/>[agents]"]
  node_validation["Repository validation<br/>[validate.ts]"]
end

node_user(("Project maintainer"))
node_target["Target repository"]

node_user -->|"installs into"| node_install
node_user -->|"updates in"| node_sync
node_install -->|"calls"| node_engine
node_sync -->|"calls"| node_engine
node_engine -->|"reads"| node_roles
node_engine -->|"copies"| node_standards
node_engine -->|"reads"| node_templates
node_engine -->|"renders from"| node_codex
node_engine -->|"renders from"| node_copilot
node_engine -->|"writes to"| node_target
node_engine -->|"deploys"| node_installed
node_setup -->|"regenerates"| node_localagents
node_setup -->|"uses generator"| node_engine
node_validation -->|"checks generated output"| node_engine
node_validation -->|"validates roles"| node_roles
node_validation -->|"checks drift"| node_localagents

click node_install "https://github.com/njm04/engineering-agents/blob/main/scripts/install.ts"
click node_sync "https://github.com/njm04/engineering-agents/blob/main/scripts/sync.ts"
click node_engine "https://github.com/njm04/engineering-agents/blob/main/scripts/deployment.ts"
click node_roles "https://github.com/njm04/engineering-agents/tree/main/agents"
click node_standards "https://github.com/njm04/engineering-agents/tree/main/standards"
click node_templates "https://github.com/njm04/engineering-agents/tree/main/templates"
click node_codex "https://github.com/njm04/engineering-agents/tree/main/adapters/codex"
click node_copilot "https://github.com/njm04/engineering-agents/tree/main/adapters/copilot"
click node_setup "https://github.com/njm04/engineering-agents/blob/main/scripts/setup-repo.ts"
click node_localagents "https://github.com/njm04/engineering-agents/tree/main/.codex/agents"
click node_validation "https://github.com/njm04/engineering-agents/blob/main/scripts/validate.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_roles,node_standards,node_templates toneBlue
class node_codex,node_copilot toneAmber
class node_install,node_sync,node_engine,node_installed toneMint
class node_setup,node_localagents,node_validation toneRose
class node_user,node_target toneIndigo
```

## Components

### Reusable guidance

- [Agent roles](https://github.com/njm04/engineering-agents/tree/main/agents): `agents`
- [Engineering standards](https://github.com/njm04/engineering-agents/tree/main/standards): `standards`
- [Base templates](https://github.com/njm04/engineering-agents/tree/main/templates): `templates`

### Platform adapters

- [Codex templates](https://github.com/njm04/engineering-agents/tree/main/adapters/codex): `adapters/codex`
- [Copilot templates](https://github.com/njm04/engineering-agents/tree/main/adapters/copilot): `adapters/copilot`

### Deployment

- [Install command](https://github.com/njm04/engineering-agents/blob/main/scripts/install.ts): `scripts/install.ts`
- [Sync command](https://github.com/njm04/engineering-agents/blob/main/scripts/sync.ts): `scripts/sync.ts`
- [Deployment engine](https://github.com/njm04/engineering-agents/blob/main/scripts/deployment.ts): `scripts/deployment.ts`
- **Installed guidance and agents**

### Repository maintenance

- [Local Codex setup](https://github.com/njm04/engineering-agents/blob/main/scripts/setup-repo.ts): `scripts/setup-repo.ts`
- [Generated Codex agents](https://github.com/njm04/engineering-agents/tree/main/.codex/agents): `.codex/agents`
- [Repository validation](https://github.com/njm04/engineering-agents/blob/main/scripts/validate.ts): `scripts/validate.ts`

### Other components

- **Project maintainer**
- **Target repository**

## Connections

- Project maintainer → Install command: installs into (evidence: `README.md`)
- Project maintainer → Sync command: updates in (evidence: `README.md`)
- Install command → Deployment engine: calls (evidence: `scripts/install.ts`)
- Sync command → Deployment engine: calls (evidence: `scripts/sync.ts`)
- Deployment engine → Agent roles: reads (evidence: `scripts/deployment.ts`)
- Deployment engine → Engineering standards: copies (evidence: `scripts/deployment.ts`)
- Deployment engine → Base templates: reads (evidence: `scripts/deployment.ts`)
- Deployment engine → Codex templates: renders from (evidence: `scripts/deployment.ts`)
- Deployment engine → Copilot templates: renders from (evidence: `scripts/deployment.ts`)
- Deployment engine → Target repository: writes to (evidence: `scripts/deployment.ts`)
- Deployment engine → Installed guidance and agents: deploys (evidence: `README.md`)
- Local Codex setup → Generated Codex agents: regenerates (evidence: `scripts/setup-repo.ts`)
- Local Codex setup → Deployment engine: uses generator (evidence: `scripts/setup-repo.ts`)
- Repository validation → Deployment engine: checks generated output (evidence: `scripts/validate.ts`)
- Repository validation → Agent roles: validates roles (evidence: `scripts/validate.ts`)
- Repository validation → Generated Codex agents: checks drift (evidence: `scripts/validate.ts`)