LeanOS AI Framework

LeanOS is an agent-native startup operating system for building AI-first products with strategic coherence before and during implementation.

It is not just a code generator. The CLI creates a workspace, and the AI agent operates that workspace through natural-language intent routing, departments, areas, roles, skills, playbooks and workflows.

What Exists Now

LeanOS currently includes:

• A TypeScript/Node CLI package published as lean-os.
• A create package published as create-lean-os for the standard npm create lean-os setup flow.
• A guided terminal wizard exposed through npm create lean-os and kept available through lean-os ai for compatibility.
• A generated client workspace with AGENT.md, leanos.yaml, .leanos/, <product-slug>-os/, active strategy/ and GitHub readiness files.
• A portable LeanOS Chief entrypoint through the root AGENT.md.
• A portable agent entrypoint for any model or chat surface through the root AGENT.md.
• A generated preview in examples/client-workspace/ that shows exactly what the CLI creates.

The current version is a local, file-based framework. It does not yet include hosted services, real GitHub API sync, marketplace distribution, remote auth or analytics.

Core Principle

LeanOS exists to help founders and product builders avoid jumping straight into implementation.

The central rule is:

Do not build features before the company, customer, problem, value proposition, MVP scope and validation logic are clear enough.

LeanOS supports both the early startup cycle and the ongoing product development cycle: from a new idea, to clarification, validation, scope definition, issue creation, implementation, review and learning capture.

Company as a Product

LeanOS treats the company itself as a product.

The company is not just the organization building the product. It is also an operating system with its own profile, principles, workflows, validation loops, decision history and quality rules.

In LeanOS, strategy/business/ is the source-of-truth area for that operating system. It captures:

• who the company is and who it exists for
• mission, vision and principles
• how decisions are made
• how humans and AI agents collaborate
• what has been decided and why
• which assumptions still need validation

This means product work should be coherent with the business operating model. Before creating features, issues or pull requests, LeanOS Chief should understand the business context, product strategy and validation state.

The product is what the company builds. The business is the system that decides what is worth building.

Quick Start

After the current package version is published, users can run:

npm create lean-os

The CLI asks a short set of questions and creates the LeanOS workspace in the current directory.

Validate an existing LeanOS workspace from its root:

npx lean-os validate

The validator is read-only. It reports structural drift, weak skill/playbook triggers, broken runtime index paths, obsolete generated editor artifacts, and temporary scripts outside .leanos/runtime/scratch/.

For compatibility, the same wizard remains available through:

npx lean-os ai

After generation, open the folder in your preferred AI coding environment and start in natural language:

Vamos comecar com o LeanOS.

The root AGENT.md is the portable entrypoint. It lets Claude, Codex, terminal agents, IDE assistants or other chat surfaces route the request without relying on generated command files.

LeanOS Chief

LeanOS Chief is the bootloader and dispatcher for the workspace.

It is intentionally small. It does not duplicate the whole framework. Its job is to:

• Start from AGENT.md and leanos.yaml.
• Load the minimum context needed for the user request.
• Route work through the Navigation Chain.
• Respect active departments and areas.
• Avoid missing paths and avoid inventing workflows.
• Propose source-of-truth updates before writing during startup or any routed workflow.

LeanOS does not generate editor-specific agent, prompt or command files. The root AGENT.md keeps command-like requests portable by mapping natural phrases to the right workflow or to activation_required when an area is not active yet.

Navigation Chain

LeanOS uses a department and area-first operating model:

AGENT.md -> Department AGENT.md/README.md -> Workflow or Area AGENT.md/README.md -> Role -> Skills -> Playbook -> Output

The agent should not jump directly to implementation. It should load only the smallest relevant route for the current task.

Generated Workspace

The generated client workspace separates LeanOS runtime files from the client's operating structure:

.github/
.leanos/
<product-slug>-os/
AGENT.md
leanos.yaml
README.md

.github/

GitHub readiness files:

• PR template
• issue templates
• LeanOS GitHub setup, branch rules, PR validation rules and project sync contract

.leanos/

LeanOS local support:

• runtime/agent/ operating rules for LeanOS Chief
• runtime/context/ current focus, next actions and workspace summary
• runtime/index/ routing maps for departments, areas, roles, skills, playbooks and workflows
• runtime/scratch/ local ignored scratch area for temporary scripts and probes
• runtime/traces/ local diagnostics when explicitly requested
• standard/ standard library for creating and validating LeanOS assets

.leanos/standard/

The standard library for creating and validating LeanOS assets:

• templates
• checklists
• instructions
• examples
• naming and navigation rules

Client Departments

Active root departments live inside <product-slug>-os/. The initial MVP scaffold starts Strategy-first:

• strategy/

Operations and Growth are available for progressive activation when the founder reaches the right stage. Each active root department has:

• AGENT.md
• README.md
• department.yaml
• workflows/

Roles, skills and playbooks live inside internal areas, not directly in the root department.

Initial active areas:

• strategy/business/
• strategy/product/
• strategy/roadmap/

Available later through activation:

• operations/product-ops/
• operations/product-ops/mvp/
• operations/design/
• operations/engineering/
• operations/devops/
• operations/security/
• growth/customer-experience/
• growth/marketing/
• growth/finance/

Startup Intent

Startup is handled by natural-language intent through root AGENT.md.

It loads the workspace map, summarizes the current state and proposes Strategy-first source-of-truth updates.

During startup, LeanOS Chief may propose updates to:

• .leanos/runtime/context/workspace-summary.md
• .leanos/runtime/context/current-focus.md
• .leanos/runtime/context/next-actions.md
• Strategy source-of-truth files such as business profile, product brief, ICP, validation notes and roadmap context

In the MVP scaffold, lightweight validation lives in strategy/product/knowledge/validation-notes.md. Formal discovery can be designed later as a separate optional capability, but it is not part of the default MVP scaffold.

It must not modify during init:

• roles/
• skills/
• playbooks/
• workflows/
• .leanos/standard/
• .github/
• product code
• Operations or Growth files unless the user explicitly asks after init

Roles, skills, playbooks and workflows are operating assets. They are used by the model to work, but they are not enriched with company/product context during startup.

CLI Development

Install dependencies:

pnpm install

Build the CLI:

pnpm build

Run the CLI locally:

pnpm --filter lean-os dev ai

Run the built CLI:

node packages/cli/dist/index.js ai

Generated Client Workspace Preview

examples/client-workspace/ is a generated preview of the workspace LeanOS creates for a client.

Do not edit it manually. It is generated from the real CLI template.

Regenerate it with:

npm run generate:client-workspace

Validate that it is synchronized with the template:

npm test

The tree view lives in:

examples/client-workspace-tree.md

Useful Scripts

npm run generate:client-workspace
npm run refresh
npm test
npm --prefix packages/cli run build
node packages/cli/scripts/validate-generator.mjs
node packages/cli/dist/index.js --help

Publishing

LeanOS publishes two npm packages:

• lean-os: the operational CLI.
• create-lean-os: the wrapper that powers npm create lean-os.

Before publishing, bump both package versions as needed, commit the framework changes, and prepare npm auth locally. Do not paste npm tokens into chat or committed files.

PowerShell token setup:

$secureToken = Read-Host "Cole seu token npm granular" -AsSecureString
$token = [System.Net.NetworkCredential]::new("", $secureToken).Password
Set-Content -LiteralPath ".npmrc" -Value "//registry.npmjs.org/:_authToken=$token" -Encoding ASCII
Remove-Variable token, secureToken
npm whoami

Then run the release runbook:

npm run release:npm

The runbook validates npm auth, clean git state except local .npmrc, npm test, build, package dry-runs, publishes lean-os before create-lean-os, verifies npm registry versions, and removes .npmrc after the publish attempt.

After publishing, users can create a new LeanOS workspace with:

npm create lean-os

Example Agent Requests

Vamos comecar com o LeanOS.
Help me define the ICP.
Turn this idea into an MVP.
Create a roadmap for the first MVP learning cycle.
Check if this MVP is coherent.
Sync confirmed Epics and Features with GitHub Projects.
Start working on the authentication issue.
Review this PR against the MVP scope.
Create a new UX research role using LeanOS standards.

Summary

LeanOS turns an AI coding agent into an AI-first startup operator.

The CLI prepares the workspace. LeanOS Chief reads the workspace, routes the work and keeps product execution connected to strategy, validation and learning.