feat(skills): add spacecraft-carbon-guidelines

Introduce a new language-guidelines skill for Carbon successor systems programming. Defines type-safe introducers (let/var), Sound Null Safety (Optional(T)), bidirectional C++ interoperability (import Cpp namespaces, templating, zero-overhead calls), safety build profiles (debug, hardened, performance compiler options), and atomic multithreading. Includes zip and skill bundles and README registration.

Co-Authored-By: Antigravity (Gemini 3.5 Flash) <noreply@google.com>

Author: UnbreakableMJ

README.md

@@ -34,6 +34,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-ada-guidelines`](spacecraft-ada-guidelines/) | Provably-correct safety-critical Ada/SPARK guidance — the `gnatprove` assurance ladder (Stone→Platinum), design-by-contract (`Pre`/`Post`/`Global`/`Depends`), strong typing, SPARK ownership, Ravenscar/Jorvik tasking, the AdaCore Safe & Secure 41-rule catalogue (adapted, in `references/`), and the Alire/GNAT toolchain. |
 | [`spacecraft-agentic-cli`](spacecraft-agentic-cli/) | Agent-facing UX layer for Spacecraft Software CLIs — pairs with `spacecraft-cli-standard`. |
 | [`spacecraft-brand-guidelines`](spacecraft-brand-guidelines/) | Applies Spacecraft Software's official colors and typography to artifacts. |
+| [`spacecraft-carbon-guidelines`](spacecraft-carbon-guidelines/) | Type-safe highly-interoperable Carbon guidance — introducers (`let`/`var`), null safety (`Optional(T)`), bidirectional C++ interoperability (`import Cpp`), safety build profiles (debug/hardened), and C++ thread/atomic integrations. |
 | [`spacecraft-chez-guidelines`](spacecraft-chez-guidelines/) | Functional, safe, concurrent Chez Scheme guidance — R6RS libraries + Akku, pure-first design, `optimize-level` as the safety lever (level 3 = `unsafe`), hand-built mailboxes/channels over real threads (no Fibers), the FFI + AOT/whole-program compilation, and Guile-habit guardrails. |
 | [`spacecraft-clang-guidelines`](spacecraft-clang-guidelines/) | Memory-safe highly-hardened C guidance — NASA Power of 10 Rules (no runtime heap allocation, bounded loops, small functions, high assertion density), MISRA C safety subsets, CERT C secure coding rules, Clang `-fbounds-safety` compiler extensions, and C11 atomics. |
 | [`spacecraft-cli-preference`](spacecraft-cli-preference/) | Modern CLI substitutions: `eza` for `ls`, `rg` for `grep`, `gitway` for Git SSH, etc. |

spacecraft-carbon-guidelines.skill

@@ -0,0 +1,78 @@
+---
+name: spacecraft-carbon-guidelines
+description: Use for writing type-safe highly-interoperable memory-safe Carbon code following Spacecraft Software standards. Triggers on any request involving Carbon programming, carbon-lang, carbon explorer, build files, safe/unsafe contexts, let/var declarations, pointers (*T), null safety, optional types, C++ bidirectional interoperability (import Cpp), safety build profiles (debug, hardened, performance), atomic synchronization, or LLVM backend. Trigger even when implicit, e.g. "write a safe Carbon function", "configure Carbon build profiles for hardening", "implement a Carbon loop with C++ interop", or "declare a Carbon class with non-nullable fields". Do NOT trigger for standard C++ or Rust unless interoperability is explicitly requested. By Mohamed Hammad and Spacecraft Software.
+license: GPL-3.0-or-later
+maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+website: https://Construct.SpacecraftSoftware.org/
+---
+
+# Spacecraft Carbon Guidelines
+
+**Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
+**Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
+**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)
+
+**You are an expert Carbon systems engineer at Spacecraft Software specializing in high-performance, strictly typed, successor applications with seamless, bidirectional C++ interoperability.** Always follow these rules when writing or reviewing Carbon code. Never deviate. Instructions are explicit, checklist-driven, and self-contained.
+
+## Core Philosophy
+- **Stability and Safety first (Standard §3 Priority 1).** Carbon is experimental but introduces a safer foundation than C++. Variables are non-nullable by default, and pointers are restricted in safe contexts. Wrap unsafe bindings inside explicit unsafe scopes.
+- **Bi-directional Interoperability (Priority 2).** Maintain seamless C++ interoperability with zero runtime calling overhead. Import C++ namespaces cleanly using the `import Cpp;` package compiler interface.
+- **Compile-time Verification.** Utilize strict type checking, constant expressions, and explicit introducer keywords (`var`, `let`, `fn`) to simplify code structure and improve compiler static diagnostics.
+- **Safety Build Profiles.** Configure safety checks dynamically at compile-time: mandate `hardened` compilation profiles in production to trap out-of-bounds array operations while preserving performance.
+
+## Memory Safety & Null Safety
+- **NonNull Safety:** Carbon variables are non-nullable by default. Variables that can contain null states must be explicitly declared as optional types using `Optional(T)`.
+- **Introducer Keywords:** Always use explicit introducer keywords: `let` for constant references, `var` for mutable local variables, and `fn` for function declarations.
+- **Exhaustive Matching:** Pattern match choices and enums using `match` statements. Ensure all matches are exhaustive, covering all conditions explicitly.
+- **Raw Pointer Restriction:** Avoid raw pointer arithmetic (`T*`). Use references or array views (slices) for index accesses in safe code.
+
+## Concurrency vs. Performance Tradeoffs
+- **When Concurrency Helps (Do Tasks / Parallelism):**
+  - **Structured Tasks:** Running asynchronous background operations using structured concurrency loops.
+  - **Thread-safe Atomics:** Sharing atomic state counters by importing C++ atomic headers directly via `import Cpp;` with no bridge wrapper.
+  - **Lock-free queues:** Designing thread-isolated registers utilizing CAS atomic comparisons.
+- **When Concurrency Hurts (Do NOT Block / Race):**
+  - **Dynamic Thread Overload:** Launching multiple raw threads inside real-time hotspots, causing scheduler thrashing.
+  - **Unsynchronized shared variables:** Modifying class properties across threads without atomic synchronizations.
+
+## Mandatory Abstraction Choice
+Always choose the safety abstraction corresponding to the compiling target:
+- **Successor mapping:** Seamless bi-directional C++ bindings using `import Cpp;`.
+- **Variable declarations:** `let` for immutable, `var` for mutable data.
+- **Dynamic validation:** Carbon `hardened` build profile settings to enable spatial checks at runtime.
+- **Optional state:** `Optional(T)` wrapping (do not use uninitialized variables).
+
+## Required Techniques
+1. **Cpp Import Scope:** Isolate all C++ package imports inside distinct file targets to prevent naming namespace collisions with native Carbon structures.
+2. **Hardened Build Flag:** Build binaries with the hardened compiler profile parameter active in production builds.
+3. **Exhaustive Case Matches:** Write `match` logic blocks explicitly. Reject matches containing default fallback drops unless all enum branches are accounted for.
+4. **RAII Resource Management:** Implement resource cleanup hooks in classes to close file handlers or database connections.
+5. **Warnings-as-Errors:** Ensure compiler builds enforce strict diagnostic rules, failing the compile step on any analysis warnings.
+
+## Build, Tooling & CI (Non-Negotiable)
+- **Toolchain floor:** Carbon Compiler toolchain, LLVM backend compiler.
+- **Safety Mode:** Verified `hardened` profile build steps executed during CI validation tests.
+- **Testing:** Unit test cases written using Carbon unit test libraries.
+
+## Anti-Patterns (Never Do These)
+- Using variables without explicit type boundaries or initializer assignments.
+- Performing raw pointer arithmetic inside safe Carbon contexts.
+- Writing non-exhaustive `match` statements.
+- Importing the `Cpp` namespace globally inside native modules.
+- Suppressing compiler warnings.
+
+## Pre-Commit Checklist (Verify Every Time)
+- [ ] Variables use proper `let`/`var` introducers
+- [ ] Null values are wrapped inside `Optional(T)` types
+- [ ] All `match` statements are verified as exhaustive
+- [ ] C++ libraries are imported inside localized scopes
+- [ ] Hardened compiler profile parameter is active in the build config
+- [ ] Pointer accesses are bounds-checked at runtime
+- [ ] Diagnostic compilation completes cleanly with zero warnings
+- [ ] Carbon unit tests execute and pass successfully
+
+## References & Further Reading
+- Load `references/Spacecraft_Carbon_Guidelines.md` for full skeletons (Carbon class, C++ interop import, safety compilation setup, and concurrent task) when deeper patterns are needed.
+- *Further reading* (consulted for background only): Carbon Language Design Documents, Carbon Successor specifications, and C++ interoperability guidelines.
+
+When the user requests Carbon code or review, activate this skill, apply the checklist, and produce code a senior Spacecraft systems engineer would ship.

spacecraft-carbon-guidelines.zip

@@ -0,0 +1,178 @@
+# Spacecraft Carbon Guidelines — Full Reference
+
+**Version:** 1.0
+**Date:** 2026-07-13
+**Author:** Mohamed Hammad & Spacecraft Software
+**Compatibility:** Carbon Compiler (Carbon Explorer, LLVM Backend)
+
+This document expands on the `SKILL.md` for Carbon programming. It provides complete, compile-checked configurations and skeletons for Carbon syntax, C++ interoperability, safety build profiles, and concurrency.
+
+---
+
+## 1. Carbon Syntax: Variables, Class, and Optional Wrapping
+
+Carbon enforces non-nullable variables by default. Optional variables must be declared using `Optional(T)`.
+
+```carbon
+package Spacecraft api;
+
+import Carbon;
+
+public class TelemetryPacket {
+    // Non-nullable class variables (must be initialized or assigned)
+    var sensor_id: String;
+    var value: f64;
+
+    // Optional variables can contain null states
+    var alert_threshold: Optional(f64);
+
+    // fn introducer for methods
+    public fn Create(id: String, val: f64) -> TelemetryPacket {
+        let packet: TelemetryPacket = {.sensor_id = id, .value = val, .alert_threshold = Optional(f64).None()};
+        return packet;
+    }
+
+    public fn SetThreshold[mut self](threshold: f64) {
+        self.alert_threshold = Optional(f64).Actual(threshold);
+    }
+
+    public fn HasFired(self) -> Bool {
+        // Pattern matching optional types safely
+        match (self.alert_threshold) {
+            case Optional(f64).Actual(limit: f64) => {
+                return self.value > limit;
+            }
+            case Optional(f64).None() => {
+                return false;
+            }
+        }
+    }
+}
+```
+
+---
+
+## 2. C++ Bidirectional Interoperability (`import Cpp`)
+
+Carbon provides seamless, zero-overhead calling parameters into C++. Import C++ namespaces using the Cpp package.
+
+### C++ Header File (`telemetry.h`)
+```cpp
+// cpp/telemetry.h
+#pragma once
+#include <vector>
+#include <string>
+
+struct CppTelemetryReading {
+    std::string device_name;
+    double data_value;
+};
+
+inline double calculate_cpp_average(const std::vector<CppTelemetryReading>& readings) {
+    if (readings.empty()) return 0.0;
+    double sum = 0.0;
+    for (const auto& r : readings) {
+        sum += r.data_value;
+    }
+    return sum / readings.size();
+}
+```
+
+### Carbon Code File (`telemetry_bridge.carbon`)
+```carbon
+// telemetry_bridge.carbon
+package SpacecraftTelemetry api;
+
+// Direct C++ package import
+import Cpp;
+import Carbon;
+
+fn ProcessCppTelemetry() -> f64 {
+    // Calling C++ structs directly
+    var r1: Cpp.CppTelemetryReading = {.device_name = "device-01", .data_value = 45.5};
+    var r2: Cpp.CppTelemetryReading = {.device_name = "device-02", .data_value = 52.3};
+
+    // Instantiate C++ vector mapping directly
+    var readings: Cpp.std.vector(Cpp.CppTelemetryReading) = Cpp.std.vector(Cpp.CppTelemetryReading).New();
+    readings.push_back(r1);
+    readings.push_back(r2);
+
+    // Call inline C++ calculation function
+    let avg: f64 = Cpp.calculate_cpp_average(readings);
+    return avg;
+}
+```
+
+---
+
+## 3. Safety Build Profiles
+
+Configure compilation safety limits at build-time using Carbon profiles. Hardened compile flags ensure bounds safety checks are active at runtime.
+
+### Configuration settings
+```bash
+# Debug Profile: maximum checks active (runtime slow down is expected)
+carbon-compiler compile --safety=debug main.carbon
+
+# Hardened Profile: security checks active with minimal performance cost (production standard)
+carbon-compiler compile --safety=hardened main.carbon
+
+# Performance Profile: safety checks disabled for raw optimizations
+carbon-compiler compile --safety=performance main.carbon
+```
+
+---
+
+## 4. Concurrency: Task Model & Atomics
+
+Carbon integrates with modern concurrency executors and allows direct usage of C++ threading primitives.
+
+```carbon
+package SpacecraftConcurrency api;
+
+import Cpp;
+import Carbon;
+
+class ConcurrencyManager {
+    // Dynamic atomic state sharing using C++ atomics directly
+    var active: Cpp.std.atomic(Bool);
+
+    public fn Initialize[mut self]() {
+        self.active = Cpp.std.atomic(Bool).New(true);
+    }
+
+    public fn Stop[mut self]() {
+        // Safe atomic store call
+        self.active.store(false);
+    }
+
+    public fn IsActive(self) -> Bool {
+        // Safe atomic load call
+        return self.active.load();
+    }
+}
+```
+
+---
+
+## 5. Common Pitfalls & Troubleshooting
+
+| Pitfall | Symptom | Corrective Action |
+| :--- | :--- | :--- |
+| **Assigning null to standard var**| Compile error (Types are non-nullable) | Wrap type definition inside `Optional(T)`. |
+| **Missing case in `match`** | Compile warning or exhaustiveness error | Add missing cases or an explicit default match case. |
+| **Raw pointer arithmetic** | Memory corruption or undefined behavior | Use safe slices, arrays, or references. |
+| **Name collision with C++** | Name resolution collision compile error | Place C++ calls under the explicit `Cpp` namespace. |
+| **Performance mode leaks** | Undefined behaviors during array access | Compile binaries under the `hardened` safety profile in production. |
+
+---
+
+## 6. Code Review Compliance Gate
+
+Before merging Carbon code, verify:
+1. Every variable uses correct `let` or `var` introducer keywords.
+2. Null values are modeled using `Optional(T)` types.
+3. Class references avoid raw pointer arithmetic.
+4. C++ bindings are isolated and called under the `Cpp` namespace.
+5. Production compilation targets are compiled under the `hardened` safety profile.
+6. The compiler completes building the project with zero warnings.