engineering-ops

---
name: engineering-ops
description: "Engineering project maintenance and I&C estimation pipeline. This skill should be used when the user asks to '/a-eng status', '/a-eng-estimate', 'I&C estimation', 'engineering project', 'toolkit', or manages multi-discipline engineering deliverables."
mode: [engineering]
effort: high
---

# Engineering Ops

Two capabilities: **Project Maintenance** (8 subcommands) + **Estimation Pipeline** (4-agent chain).

**Model**: Sonnet for all agents. Opus for synthesis + HITL decisions.
**Scope**: Any I&C project with config SSoTs in `config/` directory.

## Project Detection

Auto-detects from: CWD (`{PROJECT}-Workspace/` or `04_ESTIMATION_TOOLKIT/`) → WORK.md → explicit arg → toolkit files (`config.py` + `run_estimation.py`).

---

## Part 1: Subcommands

| Command | Description | HITL Gate |
|---------|-------------|-----------|
| `status` | Dashboard: I/O, hours, packages, sprint %, blockers | - |
| `update` | Sync metrics across PROJECT-MASTER, STATUS-DASHBOARD, INDEX | If variance > 5% |
| `links [--fix\|--strict]` | Validate/repair links, detect orphans | - |
| `map` | File structure tree with cross-references | - |
| `checklist <level>` | Interactive maintenance (daily/weekly/monthly/phase/quarterly) | - |
| `recalc` | Run Python recalc, compare documented vs calculated I/O | If variance > 5% |
| `plan [init\|sync\|gate\|risk]` | Execution plan management (milestones, triple tracking, risk register) | If milestone delayed > 3d |
| `toolkit [status\|run\|validate]` | Estimation toolkit operations, GYOW benchmark validation | If validation fails |

### Checklist Levels

| Level | Duration | Focus |
|-------|:--------:|-------|
| `daily` | 5 min | Status, blockers, sprint |
| `weekly` | 15 min | Dashboard sync, links, insights |
| `monthly` | 1 hour | Dataflow review, I/O validation |
| `phase` | 30 min | HITL gates, deliverables |
| `quarterly` | 2 hours | Template evolution, lessons learned |

---

## Part 2: Estimation Pipeline (4-Agent Chain)

```
data-extractor → estimation-analyst → qc-validator → deliverable-generator
   (sonnet)          (sonnet)           (sonnet)          (sonnet)
```

**Pre-flight**: Locate project path + config SSoTs (`config/*.json` or `00_DATA/config/*.json`). No config = stop.

| Step | Agent | Action | HITL Gate |
|------|-------|--------|-----------|
| 1 | Data Extractor | Extract instruments, I/O by type, equipment, P&ID refs | Present summary → "Proceed to estimation?" |
| 2 | Estimation Analyst | Hours per type (Asset x Labor Matrix), factors, rates, cost per package, Resource Planning table | Present total cost + hours → "Proceed to QC?" |
| 3 | QC Validator | Verify rates vs config, factors applied, I/O cross-ref, FEL accuracy, no blended rates | Report PASS/WARN/FAIL → if FAIL: fix or proceed? |
| 4 | Deliverable Gen | BOE narrative + system CSV + package README | Present final summary |

## Error Recovery

| Error | Action |
|-------|--------|
| No config files | Ask user for path or create template |
| Incomplete extraction | Ask for missing files, re-run Step 1 |
| QC FAIL (rates) | Fix estimation, re-run Steps 2-3 |
| QC FAIL (totals) | Investigate delta, present to user |
| Deliverable gen fails | Re-run Step 4 with error context |

## HITL Checkpoints (NON-NEGOTIABLE)

User confirmation required before: modifying I/O counts/hours, archiving/deleting files, cleanup operations, updating validated metrics, proceeding between estimation steps.

---

## Part 3: Engineering Operations Domain Overview

Engineering operations at AXOIQ span three integrated products on a shared **deterministic engineering chain**. The chain is the SSoT for any cost/hours/material flow — never hardcode totals, never bypass a stage.

```
┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌───────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐
│ IMPORT  │ → │ CLASSIFY │ → │ ENGINEER │ → │ SPEC GRP │ → │ E-BOM │ → │ PROCURE │ → │ESTIMATE │ → │ OUTPUTS │
└─────────┘   └──────────┘   └──────────┘   └──────────┘   └───────┘   └─────────┘   └─────────┘   └─────────┘
   raw         persona/         FRM/LST/      package         bill of      RFQ/PO       hours +       FRM/LST
   docs        discipline       TBE refs      grouping        materials    contracts    rates         TBE/BOE
```

Each stage emits typed artifacts persisted in PostgreSQL with `project_id` filter. JSON config files are seed-only — runtime truth lives in the DB. The same code base serves THM-012 (G Mining Tocantinzinho), BRTZ, CAJB, FORAN, GYOW (reference projects).

### Where each product plugs in

| Product | Stages owned | Repo |
|---------|--------------|------|
| **Synapse** | IMPORT → CLASSIFY → ENGINEER → SPEC GROUP → E-BOM → ESTIMATE → OUTPUTS | `projects/atlas/synapse/` |
| **GMS App** | ENGINEER + ESTIMATE (G Mining specific Brain/Ops/Capture) | `projects/atlas/synapse/gms-app/` |
| **ATLAS plugin** | Tooling for all stages (this skill, `gms-mgmt`, `plan-builder`) | `projects/atlas-plugin/` |

---

## Part 4: Persona Matrix (8 Personas)

Engineering deliverables are produced by **8 distinct personas**. Each owns a slice of the chain and consumes upstream artifacts. Project_id filter is non-negotiable on every persona view.

| Persona | Code | Owns (produces) | Consumes (reads) |
|---------|------|-----------------|------------------|
| **I&C** | `inc` | Instruments, I/O lists, control philosophy, FRM | P&IDs, equipment list, process narrative |
| **Electrical** | `el` | SLDs, cable schedules, motor lists, panel schedules | Equipment list, layout drawings |
| **Mechanical** | `me` | Equipment specs, piping classes, mechanical layouts | Process flow, line lists |
| **Process** | `pr` | PFD/P&ID, mass balance, line lists, process narrative | Feed analysis, capacity targets |
| **PM** | `pm` | Schedule, WBS, milestones, risk register, sprint plan | All disciplines + procurement status |
| **Procurement** | `pc` | RFQs, POs, vendor evaluations (TBE), expediting | E-BOM, spec sheets, vendor list |
| **Admin** | `ad` | Cost reports, contracts, change orders, invoicing | Estimates, POs, time sheets |
| **Client** | `cl` | Approvals, sign-offs, scope changes, payments | All deliverables (read-only by default) |

> **Onboarding rule**: When adding a new persona to a project, never duplicate the engineering chain. Persona = lens over the same DB; new persona = new view + RBAC scope, not a fork.

---

## Part 5: Part Lifecycle Reference (G→E→M→I→S)

Materials and instruments flow through 5 lifecycle states. Each transition is a HITL gate (engineer sign-off required) and emits an audit event.

```
G-Part  →  E-Part  →  M-Part  →  I-Part  →  S-Part
(generic)  (engineered) (manufactured) (installed) (spare)
```

| State | Source | Validation gate | Typical artifact |
|-------|--------|-----------------|------------------|
| **G-Part** | `material_catalog` (ISA 5.1 / vendor catalog) | None — catalog entry | Generic tag, no project context |
| **E-Part** | Engineer assignment to a project package | Spec sheet exists, P&ID ref present | Tag (`P-101A`), engineered spec |
| **M-Part** | PO issued + vendor confirmed | TBE pass, vendor lead-time logged | Vendor model number |
| **I-Part** | FAT pass + site delivery + commissioning | Loop check / I/O check signed | Installation cert |
| **S-Part** | Removed from active service, kept as spare | None — operational state | Spare-parts inventory |

> **Anti-pattern**: jumping G→I (skip E/M) destroys traceability. The chain enforces order; bypassing requires explicit override + decision-log entry.

---

## Part 6: MBSE 4-Layer Architecture

Synapse data model is MBSE (Model-Based Systems Engineering) split into 4 orthogonal layers. **Never mix concerns across layers** — that is the pattern that broke 2026-Q1 import wizard.

| Layer | Question | DB table | Example |
|-------|----------|----------|---------|
| **QUOI** | What is this? | `material_catalog` | "Pressure transmitter, 4-20mA, 0-100 psig" |
| **OÙ** | Where does it apply? | `package_material_rules` | "Package CIP-100 needs 12 pressure transmitters" |
| **COMMENT** | How is it presented? | `frm_item_presentation` | "Show as line item under Section 3.2 of FRM" |
| **QUI** | Who instances it? | `instruments` | "PT-101A on P&ID 45-PID-001 rev B" |

Adding a new device class typically touches QUOI + COMMENT only. Project-specific routing lives in OÙ. Field tag-out = QUI only.

---

## Part 7: Multi-Project Configuration

Synapse runs all 5 projects (THM-012 + 4 REF) on a single database with strict tenant isolation:

```python
# Every query MUST filter by project_id (no exceptions)
async def list_instruments(db, project_id: str):
    stmt = select(Instrument).where(Instrument.project_id == project_id)
    return (await db.execute(stmt)).scalars().all()
```

| Project | Code | Status | Use |
|---------|------|--------|-----|
| **Tocantinzinho** | `THM-012` | Active | G Mining flagship pilot |
| **Borborema** | `BRTZ` | Reference | Historical estimate for GYOW benchmark |
| **Cajamarca** | `CAJB` | Reference | Process variation study |
| **Foran** | `FORAN` | Reference | Cost calibration baseline |
| **Goyang** | `GYOW` | Reference | Validation target (toolkit benchmark) |

Adding a new project = `INSERT INTO projects + YAML import for company/project rules`. No code change.

---

## Part 8: 3-Tier Rule Inheritance

Engineering rules cascade from global standards down to project-specific overrides. Each tier can override but never delete the upstream rule (ISA 5.1 invariants are immutable).

```
ISA 5.1 (global)  ─┐
                   ├─→ resolved_rule = project ?? company ?? isa
Company (AXOIQ)   ─┤
                   │
Project (THM-012) ─┘
```

**YAML-driven**: New client = drop a `companies/<client>.yaml` + `projects/<project>.yaml`, no Python change. Loader: `backend/app/services/rule_inheritance.py`.

| Tier | Source | Editable | Example override |
|------|--------|----------|------------------|
| ISA 5.1 | `data/standards/isa-5.1.yaml` | NO (read-only) | Tag format `XX-NNN` |
| Company | `data/companies/<client>.yaml` | Yes (HITL gate) | Default labor rate USD 145/h |
| Project | `data/projects/<code>.yaml` | Yes | Project labor rate USD 132/h (THM-012) |

---

## Part 9: CAGM Compliance (G Mining)

G Mining requires three procurement documents per package, generated from the same DB SSoT. The `gmining-excel` skill handles formatting; engineering-ops orchestrates the data extraction and triggers.

| Doc | Purpose | Trigger | Skill |
|-----|---------|---------|-------|
| **FRM** | Bid Price Breakdown (per package) | E-BOM frozen + spec sheets approved | `gmining-excel` |
| **LST** | Material List (consolidated, per RFQ) | After FRM, before RFQ release | `gmining-excel` |
| **TBE** | Technical Bid Evaluation (vendor scoring) | Quotes received, before PO | `gmining-excel` |

> **Determinism rule**: Regenerating FRM/LST/TBE from the same DB snapshot MUST produce byte-identical Excel files. If formatting drifts, the skill is broken — never the data.

---

## Part 10: Programme Context

| Programme | Hours | Status | Plan |
|-----------|-------|--------|------|
| **AXOIQ G7** | 5,870h | APPROVED 2026-04-13 | `.blueprint/plans/mighty-cuddling-snail.md` |
| **GMS Pilot** | locked | LOCKED 2026-04-18 (G Mining) | `project_gms_pilot_approved_2026-04-18.md` |
| **Mega Plan** | 2,582h | Active | `.blueprint/plans/ticklish-tinkering-puppy.md` |

`/a-eng status` reads programme context from `.blueprint/MEGA-PLAN.md` (SSoT, 23 sub-plans, 7 phases, 65+ HITL gates).

---

## Part 11: Onboarding Track

New engineers (Charles, Jonathan G Mining, Jeremy AXOIQ) follow a 5-step persona onboarding pattern:

1. **Identity** — SSO via Authentik (OIDC + groups mapping per `lesson_authentik_provider_zero_mappings_silent_oidc_fail.md`)
2. **Persona assignment** — `atlas eng persona-onboard <name> --persona inc|el|me|...` writes to `users.persona_codes[]`
3. **Project scope** — RBAC binds `(user, project_id)` pairs; client persona defaults to read-only
4. **Tool access** — Synapse + DevHub + Forgejo team membership (auto-provisioned by `scripts/onboard-dev.py`)
5. **Validation curl** — `curl synapse.axoiq.com/api/v1/auth/me` should return persona codes + project list

Reference: `handoff-2026-04-30-evening-forgejo-authentik-sota-audit.md` (4-team architecture: owners/admins/developers/ci-bots).

---

## Part 12: CLI Extensions

```bash
# Project maintenance
atlas eng status                                         # Dashboard for active project
atlas eng update --variance 5                            # Sync metrics if variance > 5%
atlas eng checklist weekly                               # 15-min weekly check

# Persona / onboarding
atlas eng persona-onboard charles --persona inc          # Add I&C persona to user
atlas eng project-switch THM-012                         # Switch active project context

# Estimation pipeline (4-agent)
atlas eng-estimate --project THM-012 --package CIP-100   # Full chain w/ HITL gates
atlas eng-estimate --resume step3                        # Resume after QC fail

# Toolkit / benchmark
atlas eng toolkit run --project GYOW --benchmark         # Validate against GYOW reference
atlas eng toolkit validate --rates                       # Check all rates vs ISA + company tier
```

---

## Part 13: Synergy with Other Skills

| Skill | When to chain | Why |
|-------|---------------|-----|
| `vision-alignment` | Before scoping a new programme | Capture strategic intent → roadmap entry |
| `plan-builder` | After scoping, before coding | Generate 15+5-section sub-plan w/ HITL gates |
| `knowledge` | During data extraction | TEG timeline, FTS5 cross-repo search |
| `gms-mgmt` | G Mining specific status/insights | Cockpit + profiler + onboard merged |
| `gmining-excel` | After estimation completes | FRM/LST/TBE document generation |
| `decision-log` | When overriding default rule tier | Persist rationale for audit |
| `scope-check` | When estimation creep exceeds 10% | Flag drift, halt for HITL |

---

## Part 14: Anti-Patterns (forbidden)

1. **Hardcoding totals** — never `total_hours = 1500` in code. Always sum from `package_estimates` rows.
2. **Bypassing project_id filter** — every query, every endpoint, every aggregation. No exceptions, even "internal admin" routes.
3. **Forking the engineering chain per persona** — personas are views, not parallel pipelines. New persona ≠ new chain.
4. **Mixing MBSE layers** — putting "where" data in `material_catalog` (QUOI) breaks reuse across projects.
5. **Skipping G→E→M→I→S transitions** — direct G→I destroys traceability. Override requires `decision-log` + HITL.
6. **Editing ISA 5.1 tier YAML** — invariant, read-only. Override at company or project tier.
7. **Generating FRM/LST/TBE from JSON files** — DB is SSoT. JSON is seed only. Excel diffs prove drift.
8. **Blending labor rates across disciplines** — QC validator FAILs on blended rates (Step 3 of pipeline).
9. **Modifying validated metrics without `/a-eng update --variance` gate** — silent change destroys audit trail.

---

## References

- Synapse engineering chain SSoT: `projects/atlas/synapse/CLAUDE.md`
- Mega Plan: `projects/atlas/synapse/.blueprint/MEGA-PLAN.md`
- 3-tier rule loader: `backend/app/services/rule_inheritance.py`
- ISA 5.1 standard: `data/standards/isa-5.1.yaml`
- AXOIQ ecosystem map: `.blueprint/MEGA-PLAN.md` section L
- This skill audit: `.blueprint/audits/thin-skills-consolidation-2026-05-01.md` (W5.3 EXPAND)