🏗️ std-c99-proj-skill

Professional framework for pure ANSI C99 projects — as a Pi skill.

Memory arena · Containerized builds · Valgrind mandatory · -fanalyzer · Zero warnings · No recursion

Table of Contents

• Overview
• Features
• Install
• Quick Start
• Actions
• Build Targets
• Project Layout
• Compiler Flags
• Framework Rules
• Memory Arena API
• Requirements
• Documentation
• Contributing
• License

Overview

std-c99-proj-skill is an installable Pi package that provides a complete, opinionated framework for pure ANSI C99 development. It follows the Agent Skills 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/<target>/ | | 🔒 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

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 <target> [Debug\|Release] | Compile inside container → build/<target>/ | | test | test.sh <target> | Tests + Valgrind → build/<target>/ (leaks = hard failure) | | static-analysis | static_analysis.sh <target> | clang-tidy with --warnings-as-errors | | docs | docs.sh <target> | Doxygen documentation → docs/<target>/ |

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 for rationale and coding conventions.

Memory Arena API

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 for full documentation.

Requirements

• Podman — container runtime (rootless supported)
• Git — version control
• Pi — AI coding agent

Documentation

📖 User Manual — complete guide from installation to advanced usage (beginner / intermediate / advanced).

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before submitting a pull request.

License

This project is licensed under the MIT License — see the LICENSE file for details.