Codex Deepwork Skill — Auralite

Use this skill when working on Auralite inside this repository.

Purpose

This skill is for deep, milestone-by-milestone implementation work on Auralite.

It is designed to keep Codex locked onto:

• the long-term Auralite architecture,
• the current milestone objective,
• the project’s world-authoritative design,
• disciplined vertical-slice delivery,
• and high-signal progress without wandering into unrelated cleanup.

This is not a generic coding prompt. This is a project operating mode for sustained Auralite development.

Required reading order before making changes

Always read these files in this exact order before you change code:

1. docs/AURALITE_MASTER_BLUEPRINT.md
2. docs/CODEX_AURALITE_EXECUTION_PROMPT.md
3. docs/AURALITE_MILESTONE_01_BUILD_SPEC.md
4. docs/AURALITE_FILE_MAP_FOR_CODEX.md
5. docs/CODEX_AURALITE_DEEPWORK_SKILL.md

If the user gave a milestone prompt in-chat, treat that as the current task overlay on top of these files.

Non-negotiable architecture rule

The world is authoritative; agent cognition is contextual.

That means:

• backend/world state owns truth,
• frontend reads and renders backend-owned truth,
• reporting/explainability summarize backend state,
• spatial/operator surfaces are readers, not alternate simulation engines,
• and new features must preserve the separation between world, institutions, households, agents, interventions, history, and explainability.

Do not drift away from this.

Deepwork mode behavior

When using this skill, work like this:

1. Re-anchor before changing anything

Before writing code, identify:

• what milestone or slice is being implemented,
• which existing Auralite layer it belongs to,
• what must remain authoritative,
• and what should explicitly not be built yet.

2. Prefer vertical slices over broad rewrites

Always choose the smallest meaningful slice that:

• improves the project materially,
• preserves long-term architecture,
• and leaves clean extension points for future milestones.

Do not do broad cleanup unless it directly supports the current slice.

3. Reuse existing reporting/readback paths

When possible, route new operator-facing behavior through existing paths such as:

• operator_brief
• scenario_handoff
• scenario_outcome
• scenario_digest
• monitoring_watchlist
• stability_signals
• intervention_feedback_loop
• buildOperatorFocusReadback
• operatorFocusFormatting
• existing spatial readback builders

Avoid creating sibling systems when the project already has a clear path.

4. Prefer canonical sources over duplicated logic

If multiple surfaces need the same answer:

• make one canonical producer,
• keep the frontend in read-only interpretation mode,
• and avoid near-duplicate reasoning in multiple components.

5. Keep the operator experience compact

Auralite should become richer, but not noisier. When working on UI/operator surfaces:

• improve hierarchy,
• improve readability,
• improve explainability,
• reduce redundancy,
• and avoid dashboard sprawl.

6. Be explicit about deferrals

For every meaningful implementation, explicitly preserve scope discipline. State what was intentionally deferred so the milestone does not drift.

Default implementation priorities

Unless the user explicitly overrides them, optimize in this order:

1. World-authoritative correctness
2. Architectural alignment with the blueprint
3. Operator readability / explainability
4. Spatial and inspection coherence
5. Compact UI polish
6. Minor cleanup only if it supports the slice

What to avoid

Do not:

• build UI-only truth paths,
• create speculative systems disconnected from the world model,
• turn the map into a heavy GIS product,
• add prediction/recommendation engines unless explicitly requested,
• drift into exports/collaboration/accounts unless explicitly requested,
• collapse Auralite into only a dashboard,
• or perform unrelated refactors just because you notice them.

Also avoid “fake progress” such as:

• cosmetic UI changes with no authoritative wiring,
• duplicate artifacts with overlapping meanings,
• or big architecture rewrites that reset momentum.

Standard working pattern for each milestone

When implementing a milestone, follow this pattern:

A. Identify the slice

Answer internally:

• What exact milestone/slice is this?
• Which files are likely canonical?
• Which existing layers should be extended instead of duplicated?

B. Audit the existing path

Check how the current architecture already handles adjacent concepts. Prefer extending:

• the existing artifact pipeline,
• the existing view wiring,
• the existing shared formatting/readback helpers,
• and the existing map/inspector/reporting structure.

C. Implement the smallest correct extension

Build only the minimum correct set of changes needed to make the milestone real.

D. Keep outputs merge-friendly

Favor:

• consistent naming,
• clear extension points,
• stable fallback behavior,
• deterministic ordering when ranking or prioritizing,
• and compatibility with older saved world shapes when applicable.

E. Explain completion clearly

When done, report back with:

• what was implemented,
• how it fits the current architecture,
• what was intentionally deferred,
• and what was tested.

Special rules for Auralite operator/readback work

When the milestone touches operator focus, scenario readback, handoff, or explainability:

Canonical chain

Prefer this chain:

• backend reporting artifacts produce truth,
• shared frontend readback builders adapt that truth,
• formatting helpers keep wording consistent,
• surfaces render according to role.

Surface roles

Keep roles distinct:

• Map focus chip = immediate action / current spatial focus
• Scenario digest = scenario-level readback
• Scenario handoff = resume / continuity context
• Resident inspector = local selected-entity coherence

Do not let all four surfaces say the exact same thing in slightly different wording.

Focus signal rules

For focus work, keep answers compact around:

• current focus state,
• current priority,
• immediate next check,
• why it matters,
• confidence/stability/support,
• and concise evidence.

Density rule

If a new focus line is added, consider whether another line should be shortened, merged, or removed.

Special rules for map/spatial work

When working on map or spatial context:

• preserve backend/world truth,
• keep map overlays lightweight,
• prefer shared spatial readback builders,
• use the uploaded city layout reference when map fidelity is the target,
• and keep the map interactive rather than static.

Do not move simulation logic into the map.

Expected Codex output format after implementation

After completing a deepwork slice, respond in this style:

Summary

• concise list of what was implemented
• how it fits the architecture
• what was intentionally deferred

Testing

• compile/build commands run
• any limitations or unavailable tooling

Discipline check

• explicitly confirm whether the pass preserved:
  • world authority
  • shared readback consistency
  • vertical-slice scope discipline

Recommended invocation prompt for this skill

Use wording like this when starting Codex on a new slice:

Use docs/CODEX_AURALITE_DEEPWORK_SKILL.md as your operating mode for this task. Read the required files in the specified order. Then implement the requested milestone as a disciplined Auralite vertical slice. Preserve world authority, reuse existing reporting/readback paths, avoid unrelated rewrites, and explicitly state what was deferred.

Short version

If you remember nothing else, remember this:

Stay on the blueprint. Extend the existing architecture. Keep the world authoritative. Build one real vertical slice at a time. Avoid drift.