Colonist Professions

📐 Design-only. Every section of this doc is a target spec — no profession data model, training endpoints, or bonus-application code paths exist yet. Planet carries no profession columns and there is no colonist_professions table. The status marker is omitted on individual subsections to reduce noise; assume 📐 throughout unless a subsection says otherwise.

Overview

A profession layer sits on top of the three-bucket allocation model documented in colonization.md. Generic colonists are trained (irreversibly) into specialized roles that stack percentage bonuses on top of base production, defense, research, and terraforming. Professions exist to:

• Give planets distinct strategic identities (industrial hub, military bastion, research world, terraforming engine).
• Create credit and resource sinks for late-game wealth.
• Gate certain capabilities (e.g. raising max_population ceilings) behind a long-lead investment.
• Reward forward planning — training is real-time days, not turns.

Generic colonists continue to drive the fuel/organics/equipment allocations. Specialized colonists either replace generics in those roles (with a multiplier) or unlock entirely new roles (terraforming, research, planetary defense bonuses) that allocation buckets cannot express.

The 12 professions

Twelve professions, four categories. Per-1,000 / per-colonist multipliers and base costs are sourced from the legacy spec; values flagged TBD were never specified there and need to be set when the system is scheduled.

Engineering

Profession	Bonus / effect	Training time	Training cost	Prerequisite
Space Engineers	+25% ship repair speed at this planet; unlocks advanced ship-upgrade facilities	30 days	50,000 cr + 1,000 equipment per 100 trainees	Citadel L3 + Orbital Shipyard L2
Structural Engineers	−20% building upgrade costs on this planet; unlocks unique defensive structures	25 days	TBD cr + TBD equipment	Citadel L3
Mining Engineers	+30% fuel/ore production efficiency; unlocks deep-core mining facilities	20 days	TBD cr + TBD equipment	Citadel L3

Scientific

Profession	Bonus / effect	Training time	Training cost	Prerequisite
Research Scientists	+40% research speed; unlocks breakthrough techs (quantum drives, advanced sensors)	40 days	TBD cr + TBD tech	Citadel L3 + Research Lab L3
Agricultural Scientists	+35% organics production, +15% population growth; unlocks GM crops + hydroponics	30 days	TBD cr + TBD organics	Citadel L3
Medical Professionals	+20% population growth, disease prevention; unlocks advanced medical facilities	35 days	TBD cr + TBD equipment	Citadel L3
Terraform Engineers	+0.5 habitability per 1,000 engineers per month (cap +5/month at 10k engineers); unlocks atmospheric processors, ecosystem seeding, climate control	35 days	TBD cr + TBD organics + TBD equipment	Citadel L3 + Terraforming Lab L3

Military

Profession	Bonus / effect	Training time	Training cost	Prerequisite
Combat Pilots	+50% planetary defense drone effectiveness; unlocks elite drone squadrons	25 days	TBD cr + TBD equipment	Citadel L3 + Military Academy L2
Defense Coordinators	+30% turret/shield effectiveness; unlocks integrated defense networks	30 days	TBD cr + TBD equipment	Citadel L3
Strategic Analysts	Early-warning detection for incoming attacks; unlocks sector-scanning capabilities	35 days	TBD cr	Citadel L3

Economic

Profession	Bonus / effect	Training time	Training cost	Prerequisite
Trade Specialists	+25% credit generation from trade routes through this planet; unlocks private NPC-faction trade agreements	20 days	TBD cr	Citadel L3
Industrial Managers	+35% equipment production; unlocks automated factory systems	25 days	TBD cr + TBD equipment	Citadel L3

Per-100 anchor

The legacy training example pegs Space Engineers at 50,000 cr + 1,000 equipment per 100 trainees, completing in 30 real-time days. This is the only fully-specified recipe. Other professions should be priced by analogy when the system is scheduled — military and economic professions roughly equal Space Engineers; scientific (especially Research Scientists, Terraform Engineers) trend ~1.5× more expensive due to longer training.

Training mechanism

Where training happens

• Training is planet-local. A planet trains its own generic colonists into specialists; trainees do not transit between planets.
• A planet must be citadel level 3+ (Colony phase or higher) to operate a training pipeline at all. Outposts and Settlements cannot run profession training, regardless of population.
• Some professions require an additional building at a minimum level (Orbital Shipyard, Research Lab, Military Academy, Terraforming Lab — see prerequisite column above). Without the building, that profession's training option is hidden.

Time and cost

• Training time: the integer real-time days listed per profession (20–40 days). The clock runs whether the player is online or not.
• Training cost: deducted from the player's credits and from the planet's stockpile (equipment / organics / tech as specified) when training is queued, not when it completes. Cancelling a training run before completion refunds zero — costs are sunk on queue.
• Acceleration: an optional accelerate flag pays additional credits to compress training. Multiplier and per-day premium TBD.

Throughput

• Max trainees per cycle: TBD. The legacy spec implies a queue (the UI shows multiple in flight) but does not pin a numeric cap. Target rule: cap concurrent trainees at a fraction of the planet's generic colonist pool — e.g. 5% of Planet.colonists may be in training at any time.
• Queue depth: TBD. Suggest at least 5 simultaneous orders so a player can stack a long-running run (Research Scientists, 40 days) behind shorter ones.
• A rush option pays extra credits to skip remaining training time. Cost factor TBD.

Conversion

Training converts generic colonists into specialists permanently:

• Generic colonist count drops by the trainee count when the queue completes.
• Specialist count for that profession increases by the same number.
• The conversion is irreversible — there is no de-training back into generic colonists. Switching a colonist's profession requires a separate retraining flow (see below) and pays full cost again.

Profession assignment

Who can assign

• Only the planet's owner. Co-owners and team-mates with landing rights cannot queue training or reassign specialists.

What "assignment" means

Two distinct concepts:

1. Profession — what the colonist is. Set at training-completion and persistent until retrained.
2. Active assignment — what the profession is doing right now. For example, a population of 2,000 Terraform Engineers can be assigned to ACTIVE_TERRAFORMING on this planet, or held in reserve. Combat Pilots can be tied to specific drone squadrons.

A profession's bonuses (production multipliers, drone effectiveness) typically apply passively as long as the colonists exist on-planet. Active-assignment toggles matter for professions that consume resources (Terraform Engineers burn organics + equipment while assigned to active terraforming).

Switching jobs (retraining)

• Retraining cost: full training cost of the new profession (no discount for already-specialized colonists).
• Retraining time: same as the new profession's training time.
• During retraining the colonist is not productive in either profession — bonuses lapse for the duration.

Off-planet movement

Specialists are still colonists. They occupy 1 cargo space per unit if loaded onto a ship and are subject to the standard cargo-loss rule on ship destruction. Whether transferred specialists retain their profession at the destination planet is TBD — design intent leans toward yes, with a re-acclimation period of TBD days during which bonuses are halved.

Multi-role professions (Phase 3 extension)

A late-tier extension introduces hybrid professions that fill two roles at reduced effectiveness instead of one role at full effectiveness:

• Versatile Engineers — partial Space Engineer + partial Industrial Manager (ship repair and equipment production).
• Agri-Scientists — partial Agricultural Scientist + partial Research Scientist (organics yield and tech research).
• Combat-Engineers — partial Defense Coordinator + partial Industrial Manager (defenses and equipment).

Stacking percentages, training cost, and unlock requirements are TBD. Multi-role professions are scheduled for Phase 3 of the rollout (see Status summary).

Caps and limits

Specialization cap by phase

The fraction of a planet's population that can be specialized scales with the colony lifecycle phase from colonization.md:

Phase	Citadel level	Max specialized	Training available
1 — Outpost	1	0%	No
2 — Settlement	2	10%	No (training needs L3)
3 — Colony	3	25%	Yes
4 — Major Colony	4	50%	Yes
5 — Planetary Capital	5	75%	Yes

A Settlement (Phase 2) can hold up to 10% specialists if they were transferred in from another planet, but cannot train new ones locally. Outposts cannot host any specialists at all — incoming specialists revert to generic colonists or are refused.

Per-profession soft caps

Soft caps per profession (preventing a planet from trivially stacking 100% Mining Engineers) are TBD. Legacy spec does not pin numbers. Target rule: each profession is capped at a fraction of the global specialization cap, e.g. no single profession may exceed 40% of the planet's specialized headcount.

Active-assignment caps for resource-consuming professions

• Terraform Engineers: meaningful impact requires at least 500 engineers; rate caps at +5 habitability/month at 10,000 engineers. Above 10k, additional engineers add no terraforming speed (they can still passively boost research / morale via secondary roles, TBD).
• Other professions: no upper cap on bonus stacking specified. Diminishing returns beyond the planet's specialization cap is TBD.

Worked example — terraforming a volcanic world

Illustrative end-state scenario, mirroring the legacy reference project:

Planet:                  H_CLASS Volcanic
Starting habitability:   15
Target habitability:     75
Engineers trained:       3,000 (from generic colonists, 35d each)
Terraform rate:          +1.5 habitability/month (3000 / 1000 × 0.5)
Project duration:        ~40 months
Organics consumed:       ~200,000 units (drawn from planet stockpile)
Equipment consumed:      ~120,000 units
Total credits spent:     ~500,000 (training + ongoing)
Population cap change:   15,000 → 75,000 (+60,000)
Growth multiplier:       0.15× → 0.75× of base

The terraforming-rate scaling (0.5 habitability/month per 1,000 engineers) and the per-habitability-point cost ramp (+25% at 41–70, +50% at 71–90, +100% at 91–100) live in terraforming.md once that doc absorbs the Terraform-Engineer integration; this profession spec sets the engineer-side numbers only.

Cross-system effects

Profession	Touches	Mechanism
Mining Engineers	production.md	+30% multiplier on fuel/ore production for colonists allocated to fuel role
Industrial Managers	production.md	+35% multiplier on equipment production
Agricultural Scientists	production.md, colonization.md	+35% organics production, +15% colonist growth rate
Medical Professionals	colonization.md	+20% colonist growth rate, suppresses disease events
Terraform Engineers	terraforming.md	Drives the long-running habitability-raise project; consumes organics + equipment from planet stockpile while active
Combat Pilots	defense.md, galaxy/sectors.md	+50% planetary defense drone effectiveness in sector engagements
Defense Coordinators	defense.md	+30% turret + shield effectiveness
Strategic Analysts	galaxy/sectors.md	Early-warning detection of hostile fleets approaching the sector
Space Engineers	defense.md, ships	+25% ship-repair throughput at the planet's shipyard
Structural Engineers	citadels.md	−20% citadel and building upgrade costs
Research Scientists	tech / research subsystem (📐 not yet specced)	+40% research speed; unlocks tier-3 techs
Trade Specialists	trading subsystem	+25% credit generation on trade routes that originate or terminate at this planet

Bonuses stack multiplicatively with citadel-level passive bonuses and production-upgrade bonuses unless a specific subsystem doc specifies additive stacking.

Source map

All paths are targets — no current code implements profession behaviour.

Concern	Target path
Profession service (training, conversion, retraining)	services/gameserver/src/services/profession_service.py (target)
Profession data model	services/gameserver/src/models/colonist_profession.py (target)
Training queue model	services/gameserver/src/models/profession_training_queue.py (target)
Profession enum	services/gameserver/src/models/colonist_profession.py:ProfessionType (target)
Production-tick integration (Mining / Industrial / Agricultural multipliers)	services/gameserver/src/services/planetary_service.py:_calculate_production_rates (target update)
Terraforming integration (Terraform Engineer rate boost)	services/gameserver/src/services/terraforming_service.py:process_terraforming_tick (target update)
Defense integration (Combat Pilots / Defense Coordinators)	services/gameserver/src/services/combat_service.py (target update)
API — train profession	POST services/gameserver/src/api/routes/planets.py:/planets/{planetId}/professions/train (target)
API — assign / reassign	POST services/gameserver/src/api/routes/planets.py:/planets/{planetId}/professions/assign (target)
API — list profession state	GET services/gameserver/src/api/routes/planets.py:/planets/{planetId}/professions (target)
Migration adding colonist_professions + profession_training_queue tables	services/gameserver/alembic/versions/xxxx_add_profession_system.py (target)
Planet joins to profession aggregate	services/gameserver/src/models/planet.py (target update — relationship to ColonistProfession)
Player UI — profession panel + training queue	services/player-client/src/components/PlanetManagement/Professions.tsx (target)

Cross-references:

• colonization.md — population flow, allocation buckets, lifecycle phases.
• terraforming.md — habitability-raise project that Terraform Engineers accelerate.
• production.md — base production formula that Mining / Industrial / Agricultural professions multiply.
• citadels.md — citadel level gates training and the per-phase specialization cap.
• defense.md — drone, turret, and shield effects boosted by Combat Pilots and Defense Coordinators.
• galaxy/sectors.md — sector-scale combat where planetary professions amplify defenders.
• DATA_MODELS/entities.md — Planet model that grows new relationships to profession aggregates.
• DATA_MODELS/player.md — player-side credit and resource deductions for training costs.

Status summary

Every aspect of this system is 📐 Design-only:

• No colonist_professions table or profession_training_queue table.
• No profession enum on Planet or anywhere else.
• No production/defense/terraforming code path consults a profession multiplier.
• No API surface for training, assignment, or queue management.
• No player-client UI panel.

Implementation order, when scheduled, follows the legacy phase plan:

1. Phase 1 — Space Engineers, Mining Engineers, Trade Specialists, Terraform Engineers (high priority due to habitability-driven population caps).
2. Phase 2 — Combat Pilots, Research Scientists, Defense Coordinators, Agricultural Scientists.
3. Phase 3 — Medical Professionals, Structural Engineers, Strategic Analysts, Industrial Managers, plus multi-role / hybrid professions.

If this system is indefinitely deferred, file an ADR in ADR/ capturing the deferral rationale and the conditions under which it would be picked up.