initialize spec macro and standards

Signed-off-by: Onur Özkan <work@onurozkan.dev>

README.md

@@ -1,2 +1,42 @@
 # kaptan
-next-gen flight controller operating system
+
+Kaptan is a modular flight controller platform focused on deterministic bare-metal execution for flight-critical paths and strong verification discipline around the rest of the stack.
+
+The repository is currently in infrastructure setup. Formal project specifications should be linked directly from the code they govern through compile-time attributes.
+
+## Current Direction
+
+- Flight-critical runtime stays bare-metal with no RTOS in the control path.
+- The first vehicle scope is multirotor.
+- The first board support lane is Kakute F7 Mini V3.
+- Non-critical extensibility, companion integration, and user-facing tooling will be added only after core runtime and verification contracts are established.
+
+## Immediate Priorities
+
+- Create specification infrastructure without inventing the first formal spec.
+- Establish crate and board boundaries that fit the first supported hardware lane.
+- Add deterministic host-side validation before simulation and hardware automation expand.
+
+## Repository Structure
+
+- `kaptan-runtime/`: bare-metal runtime crate scaffold.
+- `tests/sitl/`: host-side simulation and deterministic verification scaffolding.
+- `tests/hitl/`: hardware-in-the-loop scaffolding.
+- `scripts/`: repository validation and developer helper scripts.
+
+## Spec Infrastructure
+
+Formal specs should be colocated with the code or board package they govern.
+
+- Implementation-linked specs should use versioned sidecar filenames such as `control_loop.v0.1.0.spec.md` next to the related module or package.
+- Rust items should link to those sidecar specs through `#[spec("...")]`.
+- Missing linked spec files must fail compilation.
+
+Example:
+
+```rust
+use kaptan_spec::spec;
+
+#[spec("control_loop.v0.1.0.spec.md")]
+pub struct ControlLoop;
+```