# ๐๏ธ std-c99-proj-skill
**Professional framework for pure ANSI C99 projects โ as a [Pi](https://github.com/badlogic/pi-mono) skill.**
[](LICENSE)
[](https://www.npmjs.com/package/std-c99-proj-skill)
[](https://agentskills.io)
[]()
[](https://podman.io)
Memory arena ยท Containerized builds ยท Valgrind mandatory ยท `-fanalyzer` ยท Zero warnings ยท No recursion
---
## Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Install](#install)
- [Quick Start](#quick-start)
- [Actions](#actions)
- [Build Targets](#build-targets)
- [Project Layout](#project-layout)
- [Compiler Flags](#compiler-flags)
- [Framework Rules](#framework-rules)
- [Memory Arena API](#memory-arena-api)
- [Requirements](#requirements)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
## Overview
`std-c99-proj-skill` is an installable [Pi](https://github.com/badlogic/pi-mono) package that provides a complete, opinionated framework for pure ANSI C99 development. It follows the [Agent Skills](https://agentskills.io) standard and can be invoked manually via `/skill:std-c99-proj` or detected automatically by the agent.
The skill scaffolds projects with a hardened memory arena allocator, strict compiler flags, containerized builds via Podman, mandatory Valgrind analysis, and clang-tidy static analysis โ enforcing professional-grade quality from the first commit. An `AGENTS.md` is generated in every project so any AI coding agent automatically follows the framework rules.
## Features
| Feature | Description |
|---------|-------------|
| ๐ง **Memory Arena** | Aligned, hardened allocator โ overflow protection, double-init guard, zero leaks |
| ๐ฆ **Containerized Builds** | All compilation inside Podman containers โ per-target output in `build//` |
| ๐ **Strict Compilation** | `-std=c99 -pedantic -Werror -Wall -Wextra -Wconversion -Wshadow` |
| ๐ฌ **`-fanalyzer`** | GCC compile-time static analysis (GCC โฅ 10) โ catches use-after-free, null deref |
| ๐ก๏ธ **Hardened Release** | `-O2 -D_FORTIFY_SOURCE=2 -fstack-protector-strong -fPIE` |
| ๐ **No Recursion** | Iteration only โ predictable stack usage, no overflow risk |
| ๐ **Valgrind Mandatory** | Every test run checks for leaks and memory errors |
| ๐งน **Static Analysis** | clang-tidy with `--warnings-as-errors` |
| ๐ **Doxygen Docs** | API documentation generated inside containers |
| ๐งช **27 Tests Included** | Arena tests with alignment, overflow, and edge case coverage |
| ๐ค **AGENTS.md** | Generated in every project โ AI agents auto-follow framework rules |
## Install
```bash
pi install npm:std-c99-proj-skill # from npm (recommended)
pi install git:github.com/ibitato/std-c99-proj-skill # from git
```
## Quick Start
```
> /skill:std-c99-proj
> Initialize a new C99 project and build it for RHEL 9
```
The agent will:
1. Run `init_project.sh` to scaffold the project (including `AGENTS.md`)
2. Run `build.sh rhel9 Debug` to compile inside a Rocky Linux 9 container
3. Run `test.sh rhel9` to execute 27 tests under Valgrind
Output goes to `build/rhel9/` โ multiple targets coexist without overwriting.
## Actions
| Action | Script | Description |
|--------|--------|-------------|
| **init** | `init_project.sh` | Scaffold project with git, templates, tests, Containerfiles, and `AGENTS.md` |
| **build** | `build.sh [Debug\|Release]` | Compile inside container โ `build//` |
| **test** | `test.sh ` | Tests + Valgrind โ `build//` (leaks = hard failure) |
| **static-analysis** | `static_analysis.sh ` | clang-tidy with `--warnings-as-errors` |
| **docs** | `docs.sh ` | Doxygen documentation โ `docs//` |
## Build Targets
All builds run inside Podman containers. Two parametrized Containerfiles cover all targets:
| Target | Family | Base Image | GCC | `-fanalyzer` |
|--------|--------|------------|-----|:------------:|
| `rhel8` | RHEL | `rockylinux:8` | 8.x | โ |
| `rhel9` | RHEL | `rockylinux:9` | 11.x | โ
|
| `rhel10` | RHEL | `quay.io/rockylinux/rockylinux:10` | 14.x | โ
|
| `debian11` | Debian | `debian:bullseye` | 10.x | โ
|
| `debian12` | Debian | `debian:bookworm` | 12.x | โ
|
| `ubuntu2204` | Ubuntu | `ubuntu:22.04` | 11.x | โ
|
| `ubuntu2404` | Ubuntu | `ubuntu:24.04` | 13.x | โ
|
Each container includes: `gcc`, `clang`, `clang-tidy`, `cmake`, `make`, `git`, `valgrind`, `doxygen`.
## Project Layout
After running `init`, the generated project has this structure:
```
my-project/
โโโ AGENTS.md # AI agent rules (auto-loaded by Pi, Claude Code, etc.)
โโโ CMakeLists.txt # C99 strict, Debug/Release flags, BUILD_TESTS option
โโโ Doxyfile # Doxygen configuration
โโโ .gitignore
โโโ containers/
โ โโโ Containerfile.rhel
โ โโโ Containerfile.debian
โโโ src/
โ โโโ main.c # Entry point using memory arena
โ โโโ mem_arena.c # Hardened arena allocator
โ โโโ utils.c # Utility functions
โโโ include/
โ โโโ mem_arena.h # Arena API (aligned, overflow-safe)
โ โโโ utils.h # Utility headers
โโโ tests/
โ โโโ test_arena.c # 27 assertions, Valgrind-clean
โโโ build/ # Per-target output (gitignored)
โ โโโ rhel9/
โ โโโ debian12/
โโโ docs/ # Per-target docs (gitignored)
โโโ rhel9/
```
## Compiler Flags
| | Debug | Release |
|---|---|---|
| **Optimization** | `-O0` | `-O2` |
| **Debug info** | `-g3` (full + macros) | โ |
| **Warnings** | `-Wall -Wextra -Werror -Wconversion -Wshadow -Wfloat-conversion -pedantic` | same |
| **Static analysis** | `-fanalyzer` (GCC โฅ 10) | โ |
| **Stack protection** | `-fstack-protector-strong` | `-fstack-protector-strong` |
| **Buffer overflow** | โ | `-D_FORTIFY_SOURCE=2` |
| **PIE** | โ | `-fPIE` |
## Framework Rules
Every project created with this skill enforces these rules as build errors:
1. **Pure C99** โ `-std=c99 -pedantic` with all warnings as errors
2. **No recursion** โ iteration only, predictable stack usage
3. **Arena-only memory** โ no direct `malloc`/`free` in application code
4. **Valgrind clean** โ `--leak-check=full --error-exitcode=1` on every test
5. **Git required** โ version control from the first commit
6. **Containerized** โ all builds inside Podman, never on host
See [`references/RULES.md`](skills/std-c99-proj/references/RULES.md) for rationale and coding conventions.
## Memory Arena API
```c
int mem_arena_init(MemArena *arena, size_t size); /* 0 on success, -1 on failure */
void *mem_arena_alloc(MemArena *arena, size_t size); /* aligned, NULL on failure */
void mem_arena_reset(MemArena *arena); /* reuse without freeing */
void mem_arena_free(MemArena *arena); /* single free, idempotent */
```
Hardened: aligned allocations, integer overflow protection, double-init guard.
See [`references/ARENA_API.md`](skills/std-c99-proj/references/ARENA_API.md) for full documentation.
## Requirements
- [Podman](https://podman.io/) โ container runtime (rootless supported)
- [Git](https://git-scm.com/) โ version control
- [Pi](https://github.com/badlogic/pi-mono) โ AI coding agent
## Documentation
๐ **[User Manual](MANUAL.md)** โ complete guide from installation to advanced usage (beginner / intermediate / advanced).
## Contributing
Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting a pull request.
## License
This project is licensed under the MIT License โ see the [LICENSE](LICENSE) file for details.