initialize spec macro and standards

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

SPECIFICATIONS.md

@@ -0,0 +1,65 @@
+# Specifications
+
+Formal Kaptan specifications should normally live next to the code item they govern.
+
+Examples:
+
+- `kaptan-runtime/src/control_loop.rs`
+- `kaptan-runtime/src/control_loop.v0.1.0.spec.md`
+- `kaptan-runtime/src/scheduler.rs`
+- `kaptan-runtime/src/scheduler.v0.1.0.spec.md`
+
+## Compile-Time Linking
+
+Code implementations should link to their governing spec through `#[spec("...")]`.
+
+Example:
+
+```rust
+use kaptan_spec::spec;
+
+#[spec("control_loop.v0.1.0.spec.md")]
+pub struct ControlLoop;
+```
+
+The attribute expands to a compile-time file inclusion guard. If the linked file does not exist, compilation fails.
+
+## Spec Format
+
+Formal specs are expected to declare these keys in YAML frontmatter:
+
+- `title`
+- `status`
+- `owners`
+
+Allowed statuses are:
+
+- `in-progress`
+- `implemented`
+- `deprecated`
+
+Owner entries must use full name and email address in this format:
+
+```text
+- Full Name <name@example.com>
+```
+
+The spec path is the identifier for linkage and traceability.
+
+- The code path plus the `#[spec("...")]` reference identifies the governing spec.
+- The version is part of the spec filename and therefore part of the spec identity.
+
+## Template
+
+Use this starter when creating a new colocated spec:
+
+```markdown
+---
+title: Replace with title
+status: in-progress
+owners:
+  - Full Name <name@example.com>
+---
+
+# TODO
+```