{"id":50775732,"url":"https://github.com/parolkar/fosm-book","last_synced_at":"2026-06-11T23:30:32.263Z","repository":{"id":341830880,"uuid":"1171647309","full_name":"parolkar/fosm-book","owner":"parolkar","description":"Finite Object State Machines - Building Business Software for the AI Age - A hands-on guide to replacing CRUD with lifecycle-driven software using Rails 8 + FOSM + AI Coding Agents.","archived":false,"fork":false,"pushed_at":"2026-03-03T13:47:12.000Z","size":285,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T17:50:13.783Z","etag":null,"topics":["finite","fosm","fsm","machine","oop-principles","rails","ruby-on-rails","state"],"latest_commit_sha":null,"homepage":"https://fosm-book.inloop.studio/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parolkar.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"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-03T13:08:55.000Z","updated_at":"2026-03-03T13:47:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/parolkar/fosm-book","commit_stats":null,"previous_names":["parolkar/fosm-book"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/parolkar/fosm-book","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parolkar%2Ffosm-book","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parolkar%2Ffosm-book/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parolkar%2Ffosm-book/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parolkar%2Ffosm-book/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parolkar","download_url":"https://codeload.github.com/parolkar/fosm-book/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parolkar%2Ffosm-book/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34222709,"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-11T02:00:06.485Z","response_time":57,"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":["finite","fosm","fsm","machine","oop-principles","rails","ruby-on-rails","state"],"created_at":"2026-06-11T23:30:31.019Z","updated_at":"2026-06-11T23:30:32.255Z","avatar_url":"https://github.com/parolkar.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Finite Object State Machines: Building Business Software for the AI Age\n\n*A hands-on guide to replacing CRUD with lifecycle-driven software using Rails 8, Hotwire, and AI*\n\n**By [Abhishek Parolkar](https://www.parolkar.com)**\n\nBased on the [FOSM paper](https://www.parolkar.com/fosm): *\"Implementing Human+AI Collaboration Using Finite Object State Machine\"*\n\n---\n\n## About This Book\n\nBusiness software has been stuck in the CRUD paradigm for three decades. FOSM (Finite Object State Machines) replaces Create/Read/Update/Delete with lifecycle-driven business logic — where every object declares its states, events, guards, side-effects, and actors. AI makes this practical by automating the specification process that was previously the bottleneck.\n\nThis book builds a complete AI-powered business management platform — **Inloop Runway** — from `rails new` to a production-capable system with 20 FOSM lifecycle entities, conversational AI bots, role-based transition authorization, a HEY-inspired inbox, and self-documenting process docs.\n\n## Structure\n\n| Part | Chapters | What You Build |\n|------|----------|----------------|\n| **I — The Paradigm Shift** | 1–3 | Understanding why CRUD fails and how FOSM + AI changes everything |\n| **II — The Foundation** | 4–7 | Rails 8 app, FOSM engine (DSL, TransitionService, audit log), first module (NDA) |\n| **III — Building the Business Platform** | 8–14 | 14 business modules: Partnerships, CRM, Invoicing, Expenses, Hiring, Leave, Time Tracking, Projects, Vendors, Inventory, Knowledge Base, OKRs, Payroll, Companies |\n| **IV — The FOSM Primitives** | 15–17 | Access Control (transition-level authorization), Inbox \u0026 Messaging (HEY-inspired), Process Documentation (code-as-docs + llms.txt export) |\n| **V — AI Integration \u0026 Beyond** | 18–21 | Bot architecture (OpenAI Function Calling), module query tools, the full FOSM + AI circle, future vision |\n| **Appendices** | A–E | Glossary, Lifecycle Reference (all 20 models), Paper Summary, Dev Setup, AI Prompt Templates |\n\n## The 20 FOSM Lifecycle Models\n\n| Model | States | Module |\n|-------|--------|--------|\n| Nda | draft → sent → partially_signed → executed / cancelled / expired | NDA Management |\n| PartnershipAgreement | draft → sent → partially_signed → active → terminated / cancelled / expired | Partnerships |\n| Referral | pending → qualified → accepted / rejected | Partnerships |\n| Contact | lead → qualified → customer → partner / churned → archived | CRM |\n| Deal | qualifying → proposal → negotiation → won / lost | CRM |\n| Invoice | draft → sent → paid / overdue / cancelled | Invoicing |\n| Expense | draft → reported → approved / rejected | Expenses |\n| ExpenseReport | draft → submitted → approved → paid / rejected | Expenses |\n| Candidate | applied → screening → interviewing → offer → hired / rejected | Hiring |\n| LeaveRequest | pending → approved / rejected / cancelled | Leave Management |\n| TimeEntry | logged → submitted → approved / rejected | Time Tracking |\n| Project | planning → active ↔ on_hold → completed / cancelled | Projects |\n| Vendor | prospect → active ↔ under_review / suspended → terminated | Vendors |\n| InventoryItem | in_stock → low_stock → out_of_stock / discontinued | Inventory |\n| KbArticle | draft → in_review → published / archived | Knowledge Base |\n| Objective | draft → active ↔ at_risk → completed / abandoned | OKRs |\n| PayRun | draft → submitted → approved → paid / voided | Payroll |\n| FeedbackTicket | reported → triaged → planned → in_progress → resolved / wontfix | Feedback |\n| InboxThread | open → assigned → waiting → resolved → closed | Inbox |\n| Company | prospect → active → suspended → dissolved | Companies |\n\n## Reading the Book\n\nThis is a [nanoc](https://nanoc.app/) static site. Each chapter is a standalone Markdown file with:\n\n- **Mermaid state diagrams** for every lifecycle\n- **Numbered code listings** (Listing N.N format)\n- **Callout boxes**: \"Why This Matters\", \"Under the Hood\", \"AI Insight\"\n- **Git checkpoints**: `git checkout chapter-N` for a working codebase at any point\n\n### Live book\n\nThe book is hosted at **[fosm-book.inloop.studio](https://fosm-book.inloop.studio)**\n\n### Build the site locally\n\n```bash\n$ gem install bundler\n$ bundle install\n$ bundle exec nanoc compile\n$ bundle exec nanoc view\n# Open http://localhost:3000\n```\n\n### Git checkpoints\n\nEvery chapter has a corresponding tag:\n\n```bash\n$ git tag -l\nchapter-01\nchapter-02\n...\nchapter-21\n\n$ git checkout chapter-07   # Working NDA module\n$ git checkout chapter-14   # All 20 FOSM models complete\n$ git checkout chapter-21   # Full book\n```\n\n## LLMs.txt\n\nThe file `content/llms.txt` is the entire book concatenated into a single plain-text Markdown file (~101,000 words, 852 KB) with a system prompt header. Feed it as context to any LLM to give it full knowledge of the FOSM paradigm:\n\n```\nYou are an AI coding agent that builds business software using the FOSM paradigm.\nUse the following book as your complete reference...\n```\n\nThis is the FOSM answer to documentation drift — one file, always current, machine-readable.\n\n## Key Concepts\n\n**The FOSM Contract:** Every business object declares a `lifecycle do...end` block with states, events, guards, side-effects, and actors. The transition log (`fosm_transitions` table) is the single source of truth.\n\n**The 8-Step Module Pattern:**\n1. Migration (with `status` column)\n2. Model with `include Fosm::Lifecycle` and `lifecycle do...end`\n3. Controller with transition actions\n4. Routes with member transition routes\n5. Views with state badges and transition buttons\n6. Bot Tool Integration (QueryService + QueryTool + ToolExecutor)\n7. Module Setting Registration (admin toggle)\n8. Home Page Tile (summary card)\n\n**The Three Primitives:**\n- **Access Control** — Transition-level authorization: \"Can user X trigger event Y on object Z?\"\n- **Inbox \u0026 Messaging** — HEY-inspired lanes with anti-burial urgency scoring\n- **Process Documentation** — `process_doc` + `doc:` keywords → auto-generated llms.txt\n\n## Reference Codebase\n\nThe companion codebase is **Inloop Runway v0.24** — a fully functional Rails 8.1 application with 127 commits, 20 FOSM models, 54 model files, 59 controllers, and 195 view templates. The `AGENTS.md` file (1,305 lines) serves as the machine-readable architecture guide.\n\n## Technology Stack\n\n| Component | Technology |\n|-----------|------------|\n| Framework | Rails 8.1 |\n| Database | SQLite |\n| Real-time UI | Hotwire (Turbo + Stimulus) |\n| Asset Pipeline | Vite |\n| CSS | Tailwind CSS |\n| Authentication | Devise |\n| AI | OpenAI API (Function Calling) |\n\n## Author\n\n**Abhishek Parolkar** — CEO of Inloop Studio. Author of the [FOSM paper](https://www.parolkar.com/fosm). Building AI-native business software.\n\n- Web: [parolkar.com](https://www.parolkar.com)\n- Twitter: [@parolkar](https://twitter.com/parolkar)\n\n## Hosting\n\nBook hosting is generously sponsored by [inloop.studio](https://inloop.studio).\n\n## License\n\nThis project is licensed under the **Functional Source License, Version 1.1, Apache 2.0 Future License (FSL-1.1-Apache-2.0)**. See [LICENSE](LICENSE) for the full text.\n\nIn short: you can use, modify, and redistribute for any non-competing purpose (internal use, education, research, professional services). The license automatically converts to Apache 2.0 two years after each release.\n\nThe names \"FOSM\", \"FOSM-AWESOME\" and the domain names \"parolkar.com\", \"parolkar.github.io/com\", \"abhishek.parolkar.com\" are the exclusive property of Abhishek Parolkar.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparolkar%2Ffosm-book","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparolkar%2Ffosm-book","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparolkar%2Ffosm-book/lists"}