Non-compiling JSX — a shared language for humans and agents.
- The Problem: Agentic coding has no layer to persist intent. Agents waste 90% of your budget reverse-engineering design decisions from
src/noise. - The Solution:
.sjsxis a non-compiling, valid JSX contract surface where humans and agents explicitly agree on architecture before implementing. - The Payoff: Pay once to sketch and lock (
[ ]→[x]). Amortize your token costs and achieve zero-hallucination, language-agnostic code generation.
Agentic coding has no layer for persisting intent.
Code captures how; comments drift; PR descriptions are not searchable. Each new agent session starts cold: it must reverse-engineer meaning from implementation — searching the codebase, inferring design decisions, and often re-asking questions humans already answered. That cost is paid in tokens, time, and wrong guesses.
.sjsx takes a different approach:
Record agreed intent first; implementation comes second.
This is not documentation for humans only. It is a contract surface both humans and agents can read, diff, and extend — without executing anything.
When intent lives only in src/, every agent session approximates:
tokens ≈ files explored + dependency hops + inferring intent from implementation noise
On a large codebase, that is not one file — it is Entwine, Qt, IPC, measure tools, and whatever else sits in the dependency graph. Worse, reverse-engineering fails silently: the agent produces a plausible story that may not match the original design decision.
Agentic systems optimize for what works now. They do not naturally preserve what we agreed and why. Without a persisted intent layer, semantics must be re-extracted from code every time.
The loop is cheaper than repeated full semantic extraction when .sjsx is the authority for intent and implementation follows it.
Reverse-engineer from src/ |
Read design/*.sjsx |
|
|---|---|---|
| Input size | O(codebase) or O(relevant subgraph) | O(design files) |
| Intent signal | Noisy — buried in how | Explicit — [x] agreed, [ ] open |
| History | Code diffs | Decision diffs |
| Re-ask cost | Every session | Once per agreement item |
| Failure mode | Silent mis-inference | Open items stay visible |
Per session:
cost(reverse) ≈ search + explore + infer + confirm (maybe wrong)
cost(loop) ≈ read design/ + read local src/
You pay once to sketch and agree ([ ] → [x]). Each later session reads a small, stable surface instead of mining architecture from thousands of lines of implementation. That is amortized intent — the main economic reason .sjsx exists.
The product is not the file extension. It is avoiding the repeated semantic-extraction tax.
| Approach | What it captures | Gap |
|---|---|---|
| OpenAPI / protobuf | API contracts | Not UI or system topology |
| Mermaid / C4 | Diagrams | Not valid code syntax; weak agent tooling |
| Storybook | Component examples | Runtime-bound to one stack |
AGENTS.md / Cursor rules |
Prose guidance | No agreement state, no structured diff |
.sjsx |
JSX topology + agreement state + git history | Requires intent-before-implementation discipline |
The combination that matters: valid JSX syntax, an agreement state machine ([ ] / [x]), and git-native semantic history — without a new language or a running framework.
.sjsx files use valid JSX/TS syntax but never enter the build pipeline.
- Passes lint (reuse existing eslint/tsconfig)
- Full editor syntax highlighting and autocomplete
- Never executed — and that is enough
Architecturally, .sjsx is JSX as architecture IR: a semantic tree that can lower to React DOM, Qt widgets, native UI, or other backends in src/. The design file stays stable; runtimes are disposable.
No new syntax. Reuse symbols the world already agrees on.
| Layer | Source | Examples |
|---|---|---|
| Design | Tailwind | cx="flex-1 px-6 bg-neutral-950" |
| System | Java/Rust abstractions | ThreadPool, Result, Option |
| UI/Event | React Native | View, TouchableOpacity, onPress |
| State | Redux (pre-16) | Store, mapStateToProps, dispatch |
Agents already know these symbols from training data. Humans sketch; agents fill the gaps — without learning a custom DSL.
Human: sketch .sjsx ([ ] = not yet agreed)
↓
Agent: fill gaps + ask questions
↓
Human: review diff → mark [x] when agreed
↓
Agreement complete → sjsx scaffold → implementation
The loop only beats reverse-engineering when intent is written here before or alongside implementation — not reconstructed afterward.
Once .sjsx is committed:
commit= snapshot of intentdiff= evolution of design decisionslog= timeline of why the project looks the way it does
No extra pipeline. No post-processing. Git is the semantic history store.
The loop stops being cheaper if .sjsx rots. Guard against drift:
- Intent first — sketch in
design/before largesrc/changes. - Open items stay open — do not mark
[x]until the decision is real. - Archive or update — when implementation diverges, fix
.sjsxor explicitly retire it; stale design is worse than no design.
For trivial, local changes (one obvious function), maintaining a design file may cost more than reading the code. .sjsx pays off on features, boundaries, and cross-layer decisions — where reverse-engineering is expensive.
/**
* @sjsx
* domain: TodoApp
* layer: system
* status: design
*
* Agreement items:
* [x] ThreadPool configuration
* [x] DB job granularity
* [ ] Error handling strategy (retry vs dead-letter?)
*/
const TodoSyncWorker = (
<ThreadPool cx="threads4 affinity0 cancel-flag">
{pendingTodos.forEach(todo =>
<DbJob
query="INSERT INTO todos (id, text, done) VALUES ({todo.id}, {todo.text}, {todo.done})"
cx="retry3 transaction"
onSuccess={id => TodoStore.dispatch(markSynced(id))}
onFailure={id => TodoStore.dispatch(markError(id))}
/>
)}
</ThreadPool>
)# Install
npm install -g sjsx
# Agreement status for a directory
sjsx status ./design
# Show unagreed items
sjsx diff todo-system.sjsx
# Generate implementation scaffold
sjsx scaffold todo-system.sjsx📁 design/
todo-system.sjsx ███████░░░ 67% (2/3)
todo-ui.sjsx ████░░░░░░ 40% (2/5)
📄 todo-ui.sjsx
domain : TodoApp
layer : ui
status : design
⚠️ Unagreed items (3) — scaffold is generated but marked TODO:
[ ] Empty-state UI design
[ ] Error-state handling
✅ Scaffold written: todo-ui.scaffold.ts
project/
├── design/
│ ├── todo-system.sjsx ← system-layer design
│ ├── todo-ui.sjsx ← UI-layer design
│ └── todo-ui.scaffold.ts ← generated scaffold
├── src/
│ └── ... ← implementation
Do not add design/ to .gitignore. That directory is the project's semantic history.
Reading it should reveal the whole picture.
Hooks hide state inside components. Implicit side effects break flow. .sjsx excludes anything that violates this principle — because a design artifact must be legible in one pass by humans and agents alike. Implementation may use hooks and indirection later; intent should not.
MIT