# Noricum Dev

> Development conventions for the Noricum C-to-Rust migration agent. Architecture decisions, crate structure, coding standards, and contribution guidelines. Use when: contributing to Noricum, noricum development, noricum architecture.

- **Type:** Skill
- **Install:** `agentstack add skill-juanmarchetto-agent-skills-noricum-dev`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [JuanMarchetto](https://agentstack.voostack.com/s/juanmarchetto)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [JuanMarchetto](https://github.com/JuanMarchetto)
- **Source:** https://github.com/JuanMarchetto/agent-skills/tree/main/skills/noricum-dev
- **Website:** https://github.com/JuanMarchetto/agent-skills

## Install

```sh
agentstack add skill-juanmarchetto-agent-skills-noricum-dev
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Noricum Development Conventions

## Architecture
- Noricum is an **agent orchestrator**, not a compiler
- C2Rust is "step zero" (subprocess), not reinvented — but often skippable (P4: `--skip-c2rust`)
- LLM agents are central from v0
- Semantic Code Map (noricum-ir) tracks metadata, not compiler IR
- rig-rs 0.31 for LLM integration (Rust-native, rustls)

## Crate Dependencies (layered)
```
noricum-cli -> noricum-core -> noricum-agents -> noricum-tools -> noricum-ir
                            -> noricum-validation -> noricum-tools -> noricum-ir
noricum-mcp -> noricum-core
```

## Coding Standards
- Edition 2024, `thiserror` for lib errors, `anyhow` for CLI
- `tracing` for logging, never `println!` in library code
- No `unwrap()` in library code
- Async with tokio
- Tests in `#[cfg(test)] mod tests` within each file
- C compiler: `-std=gnu11` (not c11, needed for POSIX like strdup), `-lm` for math

## State Machine
```
Pending -> Extracted -> Characterized -> C2RustDone -> Analyzed -> Refined -> Validated
                                                                    |
                                                            Repairing (max iterations)
                                                                    |
                                                            FallbackUnsafe
```

## Model Router (Claude 4.6 era)
- Easy: `claude-haiku-4-5` (fast, cheap)
- Medium: `claude-sonnet-4-6` (also used for analysis)
- Hard: `claude-opus-4-6` (translation, complex repair)
- Fallback: Ollama `qwen2.5-coder:32b` when no API key

## Pipeline Improvements (P0-P5, learned from miniz + genann migrations)
- **P0: Quality floor** — repair rejected if unsafe count exceeds translation baseline
- **P1: Best-version tracking** — keeps highest-score version, uses it for fallback instead of c2rust
- **P2: Per-function C2Rust context** — extracts only matching c2rust functions per chunk
- **P3: Incremental per-module** — `split_into_modules()` groups C functions by prefix
- **P4: Skip C2Rust** — `--skip-c2rust` flag; LLM often translates better without c2rust noise
- **P5: Idiomatic improvement hints** — when code compiles + diff passes but score 800 LOC (MEDIUM_FILE_LOC)
- Reduced repair iterations: >1000 LOC
- Very large file handling: >2000 LOC
- Structural summary: >800 LOC
- Quality gate: re-translate if >5 unsafe blocks
- Stall detection: 2 consecutive unchanged error counts → re-translate at temp 0.7
- Chunk targets: 400 LOC (medium), 500 LOC (very large)

## Pipeline Improvements (P30-P33, learned from miniz_zip.c 9 runs)
- **P30: Hybrid Repair Engine** — 3-phase: rule engine (free) → surgical per-function (cheap) → legacy whole-file (expensive)
- **P31: Assembly Cleanup** — fence stripping, syntax error parsing, use import merging
- **P32: Brace-Balance Validation** — detect/fix truncated module outputs before assembly
- **P32b: Smart Truncate + Re-translate** — truncate at last balanced brace, re-translate truncated modules
- **P33: Type Contract** — types-first modular migration:
  - `generate_type_contract()` in `type_contract.rs` — single LLM call before module translation
  - `ModuleSplit` struct returns `shared_context` from `split_into_modules()`
  - `resolve_header_types()` reads `#include`'d .h files for complete type definitions
  - Assembly seeds P27 dedup from contract type names
  - Key learning: shared_context only has .c file content; .h headers must be resolved separately

## Key Patterns
- Functions migrate independently, ordered by dependency graph (topological sort)
- Every migration must pass differential testing (byte-exact stdout match)
- Translation cache: `.noricum-cache/` keyed by SHA-256 of C source
- RAG patterns: successful migrations auto-added to PatternStore for future context
- Structural chunking: data model (structs/constructors) in chunk 0, logic functions in later chunks
- For multi-file C projects: type definitions live in .h headers, not .c files — must resolve includes
- Type contract prompt must enforce idiomatic Rust (no raw pointers, no C-style aliases, complete structs)

---

Powered by [Noricum](https://github.com/JuanMarchetto/noricum) — autonomous C/C++ to Rust migration agent

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [JuanMarchetto](https://github.com/JuanMarchetto)
- **Source:** [JuanMarchetto/agent-skills](https://github.com/JuanMarchetto/agent-skills)
- **License:** MIT
- **Homepage:** https://github.com/JuanMarchetto/agent-skills

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-juanmarchetto-agent-skills-noricum-dev
- Seller: https://agentstack.voostack.com/s/juanmarchetto
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.