Most software projects lie. Not maliciously -- structurally.
A file called auth.py exists, so authentication is "done." A button renders on screen, so the feature is "shipped." A test file named test_payments.py exists, so payments are "tested." A README says "fully integrated with Stripe," so billing is "working."
None of that is necessarily true. File existence is not feature reality. UI existence is not backend implementation. Test names are not coverage. Docs are not proof.
I kept running into this across every project I worked on -- AI apps, trading systems, automation tools, research platforms. The same pattern everywhere: optimistic claims, missing wiring, security bolted on as an afterthought (or not at all), and zero governance over what AI agents were actually allowed to do.
So I built something to fix it.
The problem is deeper than bad documentation
Modern coding agents are good at generating implementation. Claude, Codex, and similar tools can ship features fast.
They are much less reliable at establishing the surrounding structure serious projects actually need:
- Truth tracking. Nobody records what is actually working vs. what is claimed, partial, stubbed, dead, or misleading.
- Control governance. AI agents act without permission models, approval gates, or audit trails.
- Memory management. Every session starts from scratch. What was tried, what failed, what was decided -- all lost.
- Evaluation discipline. There's no systematic way to verify that what was built matches what was intended.
- Security architecture. Security is either absent or exists as documentation theater.
These problems compound. A project that can't tell the truth about itself can't be secured. A project that can't be secured can't be trusted. A project that can't be trusted can't scale.
Coding agents help build the project. ProjectOS helps govern it.
What I built
Khaeldur ProjectOS is a project operating layer for AI-built software. It provides a manifest-driven foundation for truth tracking, governance, repo structure, schemas, documentation patterns, and audit-oriented tooling -- so these layers do not have to be rebuilt manually in every repository.
It is not a scaffold generator. It is not just a prompt pack. It is not just a set of audit scripts. It is an attempt to codify the missing project layer that AI coding agents usually do not establish on their own.
The design principles:
- Truth over appearance. Projects should track what is actually implemented, not what sounds complete. Every feature is tracked as WORKING, PARTIAL, STUB, DEAD, MISLEADING, MISSING, or NOT VERIFIED.
- Governance before drift. Structure, rules, and review discipline should exist before the repository becomes chaotic.
- Local-first by default. Core project governance should not require unnecessary external services.
-
Explicit contracts. Project behavior, expectations, and standards should be visible and versioned in a single
projectos.yamlmanifest. - Reusable scaffolding. Teams should not have to rebuild the same operating layer in every repo.
What exists today
The v0.1 public foundation is 89 files across 16,000+ lines of real content. Not placeholders. Not aspirational stubs. Real, structured, usable material:
47 governance documents covering architecture, singularity definition, feature truth matrix, universal rules, security architecture, threat modeling, misuse modeling, access control, incident response, ISO alignment matrix, AI risk register, quality model, and more.
12 Python audit tools that run locally with zero dependencies -- repo structure audit, stub scanner, secret scanner, singularity alignment checker, release readiness verifier, integrity checker, wiring audit, and others.
A full CLI with 6 commands: init, audit, status, check, verify, doctor. 1,900+ lines, stdlib only.
5 JSON schemas for the manifest, skills, agents, workflows, and feature truth records.
8 universal prompt files for bootstrapping new projects, auditing existing repos, enforcing singularity, and establishing security posture.
9 domain pack stubs for AI apps, trading systems, OSINT, medical/vision, content/marketing, automation, local assistants, research, and agentic SaaS.
A GitHub Actions CI pipeline that runs syntax checks, repo audit, stub scan, secret scan, and release readiness on every push.
The framework is designed to be ISO-aligned (mapped to ISO/IEC 42001, 23894, 27001, and 25010) without claiming certification. Audit-friendly, not audit-theater.
Who this is for
- Teams building AI applications who need governance from day one, not as a retrofit
- Solo developers who want structured control without enterprise overhead
- Organizations migrating messy repositories toward a governed operating model
- Builders of autonomous agents who need permission boundaries and safety controls
- Anyone shipping software where truth, trust, and traceability matter
If AI is helping build the project, ProjectOS is meant to help govern the project.
What comes next
ProjectOS should currently be understood as an early-stage foundation layer. The vision is broader than the current implementation. The current value is in structure, truth modeling, schemas, and starter audits. The bigger runtime and orchestration layers are part of the direction, not yet the fully realized present state.
Near-term: Brownfield adapter for migrating existing repos non-destructively. Extended domain pack content.
Medium-term: Agent runtime with permission enforcement. Workflow engine with approval gates. Memory persistence layer. Evaluation harness.
Long-term: Multi-repo governance. Continuous truth verification in CI/CD. ISO-aligned audit evidence generation.
The repo
Everything is open source under MIT:
https://github.com/Khaeldur/khaeldur-project-os
Run the audit tools against your own projects. Look at the truth matrix. If your project can't tell the truth about itself, this might be useful.
Contributions welcome -- especially domain packs, tool improvements, and real-world governance patterns from teams who have felt this pain.
Coding agents build features. ProjectOS builds the layers they forget.
Top comments (0)