# ontology-driven-dev makes you confirm eight times before any code exists

> A Skill that turns a paragraph of business requirement into a runnable Flask and React system by way of seven YAML models, with a hard human gate at each of eight exploration stages and a forced AI chat panel bolted into the generated app. The AI API key ships cleared, and the default login is admin over admin123.

**sharptoolbox/ontology-driven-dev** — An ontology-driven business-system development skill: a three-step method of requirements exploration, ontology modeling, and application building, based on a seven-model ontology YAML and the code-paas technical foundation. Supports WorkBuddy, Claude Code, and Codex.

- Repository: https://github.com/sharptoolbox/ontology-driven-dev
- Stars: 529 · Forks: 187
- Language: TypeScript
- License: MIT
- Published: 2026-09-18 · Updated: 2026-09-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/sharptoolbox-ontology-driven-dev

## The gate has a required shape, not just a required pause

The distinguishing mechanism is the human gate, and it is specified more tightly than most. The eight exploration stages run from stage zero through stage seven: overall understanding, business objects, business functions and rules, cross-object linkage, end to end collaboration and approval flow, query statistics and reports, roles and permissions, and finally a UI prototype which is marked optional.

At the end of every stage the agent must stop and ask, and the question has a mandated format: the question itself, an AI suggestion, the reason behind that suggestion, the other available options, and a quick reply option. Enterprise specific content, called class B, must always be raised with a suggestion attached. Without confirmation the next stage does not begin.

A format requirement like that does real work. It forces the agent to show its reasoning and to offer a path other than its own preference, which turns a confirmation prompt from a rubber stamp into something a reviewer can actually act on.

## Seven models, and there is no M4

The ontology is seven YAML files with an unusual numbering scheme. M1 is the object model, M2 behaviour, M3 rules, M5 subject, M6 process, M7 query and reporting, and MU the user interface model. M4 does not exist, and the numbering skips it in the same way it skips to a two letter suffix for the UI model.

Whatever the reason for the gap, it has a practical consequence: the identifiers are not positional, so M6 does not mean the sixth model. Any tooling or mental model that assumes sequential numbering will mislabel these.

Alongside the seven files sits a `manifest.json`, and the whole set is written to a `yaml/` directory. The traceability guarantee is that every feature in the generated application traces back to an entry in the requirements document, and the consistency checks the Skill enforces before moving on are traceability, a one to one correspondence between M7 and M2, and the absence of cycles in M6 references. Those three checks are what stop the model layer from drifting away from the code layer.

## Stage two takes a deterministic input, not a conversation

The three stage split puts all the ambiguity in stage one. Stage one ends with a requirements specification document, named after the business domain, whose appendix C holds the seven model modelling input baseline.

Stage two then treats that appendix as deterministic input and explicitly does not do further large scale business decomposition. In other words, the modelling phase is not a second round of questions. It is a translation of an already confirmed document into YAML.

That is the structural decision that makes the gate meaningful. If modelling could reopen the requirements, every confirmation in stage one would be provisional and the eight gates would be theatre. Because stage two is a pure function of a signed off document, confirming stage one actually commits something.

Stage three then copies the tech base into your project and follows a ten step development order, ending with full chain integration and acceptance.

## The AI chat panel is a required step, not an optional extra

In the ten step development order for stage three, one step is singled out and marked as mandatory: implementing the right hand AI chat panel. It is not a stretch goal you can drop if the schedule is tight.

What the panel does is specified. It receives an injected ontology registry, it makes tool calls, it streams over SSE, and it sits behind a read only SQL safety boundary. In other words the generated application's assistant is wired to the semantic model rather than being a generic chat window bolted on afterwards.

The credential situation is handled honestly. The AI API key in the repository has been cleared, and you are expected to configure an OpenAI compatible large model service yourself through the system interface before using the assistant. That is the right default for a template that people copy, and it means the example runs without sending anyone's traffic anywhere until you deliberately point it at a provider.

## Four install routes, and only one adaptation point

The Skill claims no dependency on any WorkBuddy proprietary mechanism and says it runs fully on Claude Code, Codex and Cursor. The single adaptation point is that relative paths inside the Skill are rooted at the folder containing its `SKILL.md`, which each tool resolves on its own.

For Claude Code the format matches exactly, since its Skills layout uses the same `name` and `description` frontmatter, so it is a copy:

```bash
# user-level
cp -r ontology-driven-dev ~/.claude/skills/ontology-driven-dev

# or project-level
cp -r ontology-driven-dev .claude/skills/ontology-driven-dev
```

Codex has no native Skill registry, so the directory is copied into the repository and a line is added to `codex.md` or `AGENTS.md` telling it to load the `SKILL.md` when the user asks for ontology driven work. Codex then maps each stage gate to an interactive question. The sandbox needs network access to finish `npm install` and `pip install`.

Cursor, Cline and Aider get no registry at all: the file is injected as project context, into `.cursorrules` or pasted at the top of a conversation.

## The tech base ships with admin over admin123

The bundled `code-paas` base is a Flask plus SQLite plus React and TypeScript monolith that already contains system management, a process engine, a workbench and an ontology registry. The claim is that you copy it and extend it rather than assemble those pieces yourself.

The documented default account is `admin` with the password `admin123`. That is normal for a demo tech base and is stated openly rather than buried, but it is the first thing to change. This is a generated admin system with a process engine and a database, and the natural failure mode is deploying it to a reachable host with the shipped credentials intact.

The run commands are two processes on two ports:

```bash
# backend
cd code-app/backend && pip install -r requirements.txt && python app.py   # http://localhost:5000
# frontend dev
cd code-app/frontend && npm install && npm run dev                       # http://localhost:5173
```

Requirements are Python 3.10 or newer for the Flask and SQLite backend and Node.js 18 or newer for the React and Vite frontend.

## The worked example is sales contract execution, end to end

The example application is a real business workflow rather than a to do list. The domain is sales contract execution management, and the feature list covers contract registration with tiered approval, invoicing approval, collection and write-off, cross object state linkage, fixed reports, system management, and the right hand AI assistant.

Cross object state linkage is the part worth noticing. A contract, an invoice and a payment are three objects, and the interesting behaviour is what happens when one changes state and the others must follow. That is precisely the kind of rule that gets lost when a system is hand written from a description, and it is where a declared model earns its keep.

The example ships with SQLite test data and a default test account, and its own README explains how to start it and walk the full business chain. The golden example under `reference-example/` holds the requirements specification and the seven model YAML files for the same domain, so you have both the input and the output of stage one and stage two side by side.

## Five methodology documents are mandatory, not optional reading

The Skill is not a prompt file. Alongside `SKILL.md`, which holds the methodology, the three stage pipeline and the discipline rules, there is a `references/` directory of five documents described as mandatory norms.

They are the requirements exploration and confirmation prompt V9.0, which embeds the full text of the software requirements writing specification V9.0; the ontology modelling framework v9, which holds the seven model meta specification and the YAML templates; the ontology model business function development guidebook, which maps models to implementation and lays out the ten step pipeline; the AI native application technical architecture document, covering the tech stack, semantic registry, AI orchestration and SSE; and the UI and UX interface design specification, which supplies colour tokens, layout and a full CSS library.

That last one is the reason the generated applications are not all going to look the same. Colour tokens and a complete CSS library mean the design system is an input to the pipeline, so two projects generated from the same Skill will differ because the design reference differs, not because the generator is nondeterministic.

The whole thing is MIT licensed, and the code-paas tech base is MIT on the same terms.

## Conclusion

Use this Skill when you have a business requirement that genuinely needs to become an application and you are willing to spend eight rounds answering questions before a line of code is written. The traceability guarantee and the requirement to model before building are the real value here. Do not use it for a prototype you want in an hour, since the gate cannot be skipped by design. Four things to check before you commit to it. That your tooling can load a Skill at all, because Codex has no native registry and needs a line added to `codex.md` or `AGENTS.md`, and Cursor, Cline and Aider need the file injected as context rather than registered. That you change the shipped `admin` over `admin123` login before anything touches a network, since that account is the documented default of the tech base. That you supply your own OpenAI compatible endpoint through the app UI, because the key in the example is cleared. And that you are on Python 3.10 and Node.js 18 or newer with network access on first run. Licence is MIT for both the Skill and the code-paas tech base, there are no GitHub releases, and the last push to main is dated 30 September 2026.

## FAQ

### What is sharptoolbox/ontology-driven-dev?

It is an ontology driven development Skill that turns a business requirement into a runnable browser front end and back end system through three stages: requirements exploration, ontology modelling and application construction. It is built on seven model YAML files and a bundled code-paas tech base of Flask, SQLite and React with TypeScript.

### What are the seven ontology models?

M1 object, M2 behaviour, M3 rules, M5 subject, M6 process, M7 query and reporting, and MU user interface. There is no M4, so the identifiers are labels rather than positions. The seven files are written alongside a manifest.json into a yaml directory.

### Why does ontology-driven-dev stop and ask for confirmation so often?

Requirements exploration runs through eight stages and every one must pause for human confirmation before the next begins. The question must follow a required format of the question, an AI suggestion, the reason, other options and a quick reply, and enterprise specific class B content must always come with a suggestion attached.

### How do I install ontology-driven-dev on Codex?

Codex has no native Skill registry, so copy the directory into the repository with mkdir -p .codex/skills and then add a line to codex.md or AGENTS.md telling Codex to load the SKILL.md when the user asks for ontology driven work. Codex maps each stage gate to an interactive question, and the sandbox needs network access for npm install and pip install.

### What are the default credentials and the AI setup for ontology-driven-dev?

The bundled code-paas tech base uses admin with the password admin123. The AI API key committed to the repository has been cleared, so you must configure an OpenAI compatible model service through the system interface before using the generated assistant.

## Sources

- [Issues](https://github.com/sharptoolbox/ontology-driven-dev/issues)
- [License: MIT](https://github.com/sharptoolbox/ontology-driven-dev/blob/main/LICENSE)
- [README](https://github.com/sharptoolbox/ontology-driven-dev/blob/main/README.md)
- [sharptoolbox/ontology-driven-dev on GitHub](https://github.com/sharptoolbox/ontology-driven-dev)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sharptoolbox-ontology-driven-dev