{"id":51115492,"url":"https://github.com/johnfire/ispec","last_synced_at":"2026-06-24T21:31:01.513Z","repository":{"id":343223461,"uuid":"1176768849","full_name":"johnfire/ispec","owner":"johnfire","description":"A behavioral specification system — write what your software does, AI writes the code","archived":false,"fork":false,"pushed_at":"2026-03-09T13:41:53.000Z","size":64,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-03-09T16:48:57.515Z","etag":null,"topics":["ai","ai-coding","ai-tools","programming-tools"],"latest_commit_sha":null,"homepage":"https://www.christopherrehm.de","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnfire.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-09T11:03:31.000Z","updated_at":"2026-03-09T13:41:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnfire/ispec","commit_stats":null,"previous_names":["johnfire/ispec"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/johnfire/ispec","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fispec","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fispec/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fispec/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fispec/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnfire","download_url":"https://codeload.github.com/johnfire/ispec/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fispec/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34750952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-coding","ai-tools","programming-tools"],"created_at":"2026-06-24T21:30:58.708Z","updated_at":"2026-06-24T21:31:01.503Z","avatar_url":"https://github.com/johnfire.png","language":null,"funding_links":["https://paypal.me/christopherrehm001"],"categories":[],"sub_categories":[],"readme":"# .ispec — A Behavioral Specification System\n\n\u003e *Write what your software does. AI writes the code. Humans approve the contract.*\n\n---\n\n## Copyright\n\nCopyright 2026, Christopher Rehm. All rights reserved.\n\nYou may use this system to create commercial software or anything else you need.\nYou may not sell this system to others, fork it and sell it, or repackage it\nwithout written permission.\n\nFree sharing is encouraged.\n\nIf this project has helped you, consider supporting it:\n[paypal.me/christopherrehm001](https://paypal.me/christopherrehm001)\n\n---\n\n## A Note On Working With AI\n\nBefore anything else — read this. It will save you hours.\n\n**AI is not a mind reader. Humans assume too much. That combination is where projects fail.**\n\nWhen you work with an AI to build software, the quality of what you get out is entirely\ndetermined by the quality of what you put in. Vague instructions produce vague code.\nAssumed context produces wrong assumptions in the output.\n\nThe right workflow:\n\n1. Describe what you want — as completely as you can\n2. Ask the AI to ask you clarifying questions before it does anything\n3. Answer the questions fully — do not skip them\n4. Only when the AI confirms it has enough information, ask it to proceed\n5. Review the output carefully — you are the approval gate\n\nThe .ispec framework is designed around this discipline. The AI guides you through a\nstructured process. You provide the knowledge. The AI provides the structure.\nNeither one can do the other's job.\n\nIf you find yourself saying \"the AI got it wrong\" — the first question to ask is:\n\"did I give it enough information?\" The answer is usually no.\n\n---\n\n## What This Is\n\n**.ispec** is a behavioral specification language for AI-assisted software development.\n\nYou describe what your software should do in plain English. An AI translates that into\na formal specification. A compiler turns the specification into working code in whatever\nlanguage you need.\n\nThe specification exists in two views simultaneously — plain English for humans, formal\nsyntax for the compiler — generated from the same source so they can never drift apart.\nThe client reads the plain English and approves it. The compiler reads the formal spec\nand executes it. What the client approved is what gets built.\n\nThis solves a problem that has existed since the beginning of software:\n**documentation always lies, because humans wrote it and humans stopped maintaining it.**\nThe .ispec system removes humans from the synchronization loop entirely.\n\n---\n\n## The Underlying Problem This Solves\n\n**Humans assume too much.**\n\nThis is not a criticism. It is a structural fact about how humans communicate. When a\nclient describes what they want, they leave out everything that seems obvious to them.\nWhen a developer builds it, they fill in the gaps with what seems obvious to them.\nThose two sets of assumptions are never identical.\n\nThe result: software that does something slightly different from what was asked.\nEvery time. Without exception.\n\nThe .ispec framework makes assumptions explicit at every stage:\n\n- The AI asks clarifying questions before generating anything\n- The client reads and approves plain English before code is written\n- The specification is the contract — not a document that shadows the code,\n  but the source the code is generated from\n- Every decision is recorded — not just what was built, but why\n\nThe framework does not fix the assumption problem by making humans better at\ncommunicating. It fixes it by making assumptions visible and forcing them to be\nresolved before they become bugs.\n\n---\n\n## The Core Idea\n\n```\nHuman describes intent\n        ↓\nAI asks clarifying questions\n        ↓\nHuman answers fully\n        ↓\nAI generates .ispec file\n  [human]  ← plain English  — client reads this\n  [spec]   ← formal syntax  — compiler reads this\n        ↓\nHuman approves\n  (this approval is the contract)\n        ↓\nCompiler generates code\n        ↓\nRunning system\n  [human] section is now living documentation\n  forever in sync — automatically\n```\n\n---\n\n## Repository Contents\n\n```\n.\n├── README.md                              ← this file\n├── CODE_OF_CONDUCT.md                     ← community standards\n│\n├── ispec system/                          ← the core framework\n│   ├── ispec-language-spec.md             ← full language specification\n│   ├── ai-guided-workflow.md              ← AI guides you through the process\n│   ├── testing-strategy.md                ← what to test, why, and when\n│   ├── testing-setup-guide.md             ← how to set up testing (Python/pytest)\n│   ├── global.policy                      ← system-wide error hierarchy and rules\n│   └── intent.example                     ← template for your .intent file\n│\n├── reverse ispec system/                  ← going the other direction\n│   └── reverse-ispec-system.md            ← full workflow: existing codebase → .ispec framework\n│\n└── examples/                              ← real .ispec files to learn from\n    └── client-tracker.ispec               ← consultancy client tracker\n```\n\n---\n\n## Quick Start\n\n### 1. Let the AI guide you\nStart with `ispec system/ai-guided-workflow.md`. The AI runs a structured\ndiscovery process with you. You answer questions. The AI generates documents.\nYou approve at each gate. Nothing proceeds without your approval.\n\n### 2. Read the language spec\n`ispec system/ispec-language-spec.md` covers every construct with examples.\nRead it to understand what the AI is generating on your behalf.\n\n### 3. Look at a real example\n`examples/client-tracker.ispec` shows a complete domain in both the human\nview and the formal spec view.\n\n### 4. Generate code from a spec\n```\nRead \"ispec system/ispec-language-spec.md\" for the language rules.\nRead \"examples/client-tracker.ispec\" for the specification.\nGenerate Python from the [spec] section.\nOutput to generated/python/client_tracker.py\n```\n\n### 5. Bring an existing codebase into .ispec\nHave a system already running that you want to document, specify,\nor migrate to the .ispec workflow?\n\nStart with `reverse ispec system/reverse-ispec-system.md`.\nThe AI reads your codebase, identifies domains, and generates\nthe full framework document set — one .ispec per domain, plus\narch.md and context.md. Works on modern and legacy codebases.\n\n```\nRead \"ispec system/ispec-language-spec.md\" for the language rules.\nRead \"reverse ispec system/reverse-ispec-system.md\" for the process.\nThe codebase to reverse engineer is at: [your code path]\nBegin Phase 1 — Discovery.\n```\n\n---\n\n## The Full Framework\n\nThe .ispec language is one component of a larger framework.\nA complete project requires all of these documents, generated in order,\neach approved before the next is created.\n\n| File | Layer | Purpose |\n|---|---|---|\n| `.intent` | 0 — Constitution | Purpose, values, what the system will never do |\n| `context.md` | 1 — Context | The problem being solved and why |\n| `arch.md` | 1 — Architecture | Structural decisions and the reasons behind them |\n| `ispec system/global.policy` | 2 — Rules | System-wide error hierarchy and operational rules |\n| `specs/domain.ispec` | 2 — Specification | Behavioral spec per domain |\n| `phases.md` | 3 — Build plan | Phased delivery with test gates |\n| `module/domain.md` | 4 — Interface | Token-budget-aware module contracts |\n\nThe AI generates all of these through guided conversation.\nHumans approve each document before the next one is generated.\nNothing is built until the specification is approved.\nNothing proceeds to the next phase until the current phase test gate passes.\n\nSee `ispec system/intent.example` for a template to start your own `.intent` file.\n\n---\n\n## The Reverse System — Existing Code → .ispec\n\nThe .ispec framework works in both directions.\n\n**Forward:** human describes intent → AI generates spec → compiler generates code.\n\n**Reverse:** existing codebase → AI reads and analyses → complete framework documents.\n\nThe reverse system is for teams and individuals who have software already running —\nlegacy systems, inherited codebases, systems that grew without documentation — and\nwant to bring them into the .ispec framework. It is also useful for understanding\na codebase you have just inherited before modifying it.\n\n### What the reverse system produces\n\n```\ncontext.md       ← what the system does and why\narch.md          ← how it is structured and the decisions behind it\nspecs/\n  domain.ispec   ← one per identified domain\n  domain.ispec\n  ...\nglobal.policy    ← error hierarchy extracted from the codebase\n```\n\n### How it works\n\nThe reverse system operates in two phases, which must not be collapsed into one.\n\n**Phase 1 — Discovery**\n\nThe AI reads the entire codebase before generating anything. It reads structure\nfirst, then documentation, then schema and configuration, then application code,\nthen tests. From this it produces a discovery report:\n\n- Every domain identified, with confidence level and evidence\n- Every entity, operation, query, and event found per domain\n- Cross-domain dependencies mapped\n- Bugs and anomalies — things that look wrong, not just undocumented\n- Files that don't fit any domain\n- Numbered questions that require human answers before proceeding\n\nThe human reviews the discovery report and answers all questions.\nNothing is generated until the report is approved.\n\n**Phase 2 — Generation**\n\nOne document at a time, in order: global.policy → domain.ispec files\n(one at a time, each approved before the next) → arch.md → context.md.\n\nEach generated document is reviewed and approved before the next is started.\n\n### What the reverse system cannot recover\n\nThe AI can describe what the code does. It cannot know:\n\n- Why the system was built — the original problem being solved\n- Why architectural decisions were made — what was considered and rejected\n- What the intended behavior was where the code appears to be wrong\n- Business rules that exist only in someone's head\n\nThese gaps are marked explicitly as `[UNKNOWN — requires human input]`\nthroughout the generated documents. They require the humans who built\nor operate the system to fill them in. They are not optional.\n\n### The .intent file is not generated\n\nThe `.intent` file — the constitutional layer — is never generated by the\nreverse system. Values, purpose, and permanent boundaries are human decisions.\nThey cannot be recovered from code. Use `ispec system/intent.example`\nas a template and fill it in with the people who own the system.\n\n### Legacy codebases\n\nThe reverse system handles legacy codebases. Expect more gaps, more\n`[UNKNOWN]` markers, more questions, and more review cycles. The workflow\nincludes specific guidance for god classes, missing domains, implicit\ncontracts, and undocumented business rules buried in logic.\n\n### Round-trip validation\n\nOnce .ispec files are generated and approved, compile them back to code\nand compare against the original. Every difference is information:\na compiler gap, an original bug, a spec language gap, or a correct improvement.\nNone of it is noise.\n\nSee `reverse ispec system/reverse-ispec-system.md` for the complete workflow\nwith copy-paste prompts for every stage.\n\n---\n\n## The Spec Language — At A Glance\n\n### Entities\n```\nentity User\n  id:     UserId  [unique, generated, immutable]\n  email:  Email   [unique, required]\n  status: Active | Suspended | Deleted\n```\n\n### Operations\n```\noperation TransferFunds\n  inputs:\n    source:      Account\n    destination: Account\n    amount:      Money\n\n  requires:\n    source.balance \u003e= amount\n\n  ensures:\n    source.balance      == was(source.balance) - amount\n    destination.balance == was(destination.balance) + amount\n    atomic: [source.balance, destination.balance]\n\n  failures:\n    InsufficientFunds: BusinessError\n      condition: source.balance \u003c amount\n```\n\n### Queries\n```\n@query GetActiveUsers\n  find:  User\n  where: User.status == Active\n  order: User.created_at descending\n```\n\n### Events\n```\nevent FundsTransferred\n  source:         → Account  [required]\n  destination:    → Account  [required]\n  amount:         Money      [required]\n  transferred_at: Timestamp  [required]\n```\n\n### Cross-domain references\n```\nuse User from user-account\nuse Product from products\n```\n\n### Aggregates\n```\ncount(Enrollment where Enrollment.course == course\n      and Enrollment.status == Active)\n\nsum(OrderItem.unit_price * OrderItem.quantity\n    where OrderItem.order == order)\n\nexists(Session where Session.user == user\n       and Session.status == Valid)\n```\n\n---\n\n## Design Principles\n\n**The spec is the contract.**\nThe client approves the specification before any code is written.\nWhat they read is what gets built.\n\n**Documentation cannot drift.**\nThe human view and the formal spec are generated together.\nNo human maintains the sync. It is structural.\n\n**The compiler owns implementation decisions.**\nThe spec says what. The compiler decides how.\nFramework, database, optimization strategy — compiler concerns, not spec concerns.\n\n**History is the default.**\nData is append-only unless explicitly marked `history: transient`.\nMemory is cheap. Lost history is not recoverable.\n\n**Errors are citizens.**\nEvery operation declares what can go wrong, under what conditions,\nwith what context, and whether the caller can retry.\n\n**Domains are independent.**\nDomains communicate through events, not direct calls.\nOne domain failing does not cascade. Anti-fragility is architectural.\n\n**Extensions are the growth surface.**\nThe core language is small and stable.\nNew capabilities are added as named extensions.\nExisting spec files never break.\n\n**Assumptions are the enemy.**\nEvery document in this framework exists to make an assumption explicit\nand force it to be resolved before it becomes a bug.\nVague inputs produce wrong outputs. The framework demands specificity.\n\n---\n\n## The Error Hierarchy\n\n```\nSystemError          infrastructure problems — always retriable\n  DatabaseError\n  NetworkError\n  TimeoutError\n  ServiceUnavailable\n\nClientError          caller did something wrong — never retriable\n  ValidationError\n  AuthorizationError\n  NotFoundError\n  ConflictError\n\nBusinessError        business rule violated — never retriable\n  PolicyViolation\n  LimitExceeded\n  StateError\n```\n\n---\n\n## The Long-Range Vision\n\nThe .ispec system is Phase 1 of a larger vision.\n\nThe goal is a new computing paradigm: AI writes code in a purpose-built language,\nhumans approve intent at the specification level, and all existing programming\nlanguages become compilation targets on the way to machine code or WebAssembly.\n\n```\nPhase 1 (now)\n  .ispec → Python / JavaScript via Claude Code\n  Prove the model. Ship real software.\n\nPhase 2\n  Deterministic local compiler\n  Multiple language targets\n  AI in the spec generation pipeline only\n\nPhase 3\n  AI-native intermediate representation\n  Dense, semantically rich, target-agnostic\n  Existing languages become irrelevant\n\nPhase 4\n  IR compiles directly to machine code / WebAssembly\n  One language. AI writes it. Humans approve intent.\n```\n\n---\n\n## Status\n\n**Pre-prototype. Active development.**\n\nThe language is designed. The compiler is not yet built. Current workflow uses\nClaude Code as the compiler — which proves the concept and informs the real\ncompiler design.\n\nThe spec language constructs are stable enough to write real .ispec files.\nThey will evolve based on implementation experience. Every gap found during\ncompilation becomes a language or compiler improvement.\n\n---\n\n## Contributing\n\nThe most valuable contributions right now:\n\n- Writing .ispec files for real domains and reporting what the spec language\n  could not express\n- Running the compiler workflow and reporting what Claude Code got wrong\n- Identifying constructs the language is missing\n- Improving the compiler prompt based on output quality\n- Testing the AI-guided workflow and reporting where the questions were\n  wrong or incomplete\n\nOpen an issue for language gaps. Open a PR for spec examples and workflow improvements.\n\n---\n\n## Origin\n\nThis system was designed in a single brainstorming session in March 2026,\nstarting from the question: *what would a programming language look like if it\nwere optimized for AI to write rather than humans?*\n\nThe answer turned out to be less about syntax and more about the relationship\nbetween human intent and running software — and the 50-year-old unsolved problem\nof documentation that always lies.\n\nThe root cause of that problem: **humans assume too much, and there has never been\na structural mechanism to make those assumptions visible before they became code.**\n\nThe .ispec framework is that mechanism.\n\nThe full design conversation that produced this system — every decision, every\ntradeoff, every construct designed from first principles — is preserved here:\n\n[Design Session — March 2026](https://claude.ai/share/72a4b825-5d24-499c-aa0a-67a169a2a94d)\n\nIf you want to understand why something is the way it is, that conversation\nis the primary source.\n\n---\n\n*The .ispec Language — Version 0.1 — March 2026*\n*Copyright 2026 Christopher Rehm. All rights reserved.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnfire%2Fispec","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnfire%2Fispec","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnfire%2Fispec/lists"}