🚀 AI Dev Operating System

Day-zero operating system for serious vibe coding and AI-assisted SaaS development.

Clone this repo, open it in your IDE, run Claude Code in the terminal, and let the Project Genesis Wizard take you from raw idea to product brief, business plan, prototype lab, sprint roadmap, and first coding sprint.

This repo is not a finished SaaS template. It is the operating layer you put around a new SaaS so AI coding agents do not start from chaos.

⚡ Quick start

🎯 Recommended path — "Use this template":
Click the green "Use this template" button at the top of this repo on GitHub.

Choose "Create a new repository", name it (e.g. my-new-saas), and pick Private if it's an early-stage project.
Clone YOUR new repo:
git clone https://github.com/SEU-USUARIO/my-new-saas.git
cd my-new-saas
This gives you a fresh repo under your account, with origin already pointing to YOUR repository — no accidental commits to the OS repo.

Fallback: git clone directly (only if you can't use the template button)

git clone https://github.com/lglucas/ai-dev-operating-system.git my-new-saas
cd my-new-saas

⚠️ This points your local origin to our OS repo. Before any commit, run the detach script:

bash scripts/detach-os.sh        # Linux/macOS
powershell scripts/detach-os.ps1 # Windows

The script walks you through detaching origin and (optionally) re-initializing Git. WIZARD Stage 0.5 also handles this educationally on first run.

After you have your own repo set up, open the folder in your IDE and run Claude Code in the project terminal. Paste:

Claude, vamos iniciar um novo projeto. Leia primeiro o arquivo START-HERE.md e siga exatamente as instruções dele.

Claude should read the repo structure, understand the operating system, and start the Project Genesis Wizard — including Stage 0.5 (detach from OS-origin) if you used the fallback git clone path.

📘 Need help setting up your IDE, Git, GitHub account, or Claude Code? Start here: docs/installation.md.

🤝 Want to contribute back to the OS itself (bug fix, new skill, registry pack)? See CONTRIBUTING.md. The main branch is protected — all changes go through PR.

🧠 What this gives you

A ready-to-use .claude/ runtime with agents, skills, commands, rules, and settings.
A single start file: START-HERE.md.
A guided wizard for ideation, research, business planning, review, sprint planning, prototyping, and first implementation.
Agent workflows for market research, competitor analysis, red-team critique, technical/security review, coordination, and investor-ready copywriting.
Documentation layers: PRODUCT-BRIEF.md, BUSINESS-PLAN.md, TECHNICAL-PLAN.md, SPRINTS.md, CHANGELOG.md, and session-log/.
A disposable prototype-lab/ for 3 HTML prototype directions before building the real app.
Security, privacy, changelog, sprint, and coding rules from day zero.
Optional stack packs for SaaS, Next.js/Supabase, Solana, marketplace products, and other specialized projects.

📦 External Repo Registry (v0.4.0)

A curated, on-demand catalog of trusted external repository packs that can plug into any project running this OS. Instead of pre-installing everything, the WIZARD recommends packs per project based on stack, domain, and compliance.

Layer	What it does
`docs/registry/INDEX.md`	Sortable master table of every pack — license, status, tags, last reviewed.
`docs/registry/packs/`	One-pager per repo: when to install, when NOT to install, install command, fit signals, conflicts.
`docs/registry/tags/`	Auxiliary indexes by tag (`security`, `design`, `foundations`, `stack-pack`, `ecosystem`).
`/registry-pick`	Slash command — reads the registry and outputs a prioritized recommendation for the current project. Never installs.
`registry-pick` skill	Powers the slash command and `WIZARD.md` Stage 11.5.

Adding new packs is one-pager-fast — copy the template in docs/registry/README.md, fill the fields, link from INDEX.md and the relevant tag file. Cross-link in UPSTREAM-SOURCES.md only if the pack also influenced this OS itself.

See UPSTREAM-SOURCES.md for the origin/audit map of what built this OS — that's a different question from "what should I install on top of THIS project". The registry answers the latter.

🌱 Quick wins (v0.4.3)

A small batch of cross-cutting improvements identified during the v0.4.2 comparison study against gstack and slavingia/skills:

Component	What it does
`ETHOS.md`	One-page manifesto. Every rule, agent, skill, and command in this OS must trace back to it.
`/processize`	Codify a manually-validated workflow into a documented, partially-automatable process. Validate-then-automate, never the reverse.
`/grow-sustainably`	Plan post-100-users growth without burning out the founder, the budget, or the user base. Successor to `first-100-users`.
`/multi-ai-review`	Cross-review a hard-to-reverse decision through 2–4 independent reviewer roles, then reconcile disagreements before committing.
`#agents-marketplace`	New registry tag surfacing curated skill bundles (gstack, slavingia-skills, antigravity-awesome-skills, anthropics-skills, and others).

Architectural items (plugin manifest, trust tiers, parallel sprint orchestration, marketplace migration) are deferred to v0.5 — see the v0.5 audit trail in session-log/.

🧰 Vibe Coder Non-Dev Pack (v0.3.0)

A coordinated set of agents, skills, and templates designed for non-developers building SaaS with AI. Two layers, both opt-in but on by default:

Defensive layer — protects you before things go wrong

Component	What it does
`.env.example`	Documents every secret your app may need with vibe-coder explanations.
`CLAUDE.local.md.example`	Personal overrides without leaking to the team.
`secrets-discipline`	Blocks accidental commits of API keys.
`cost-watchdog`	Flags expensive choices (Opus loops, paid tiers, scale-poor DB) before they ship.
`plain-portuguese-explainer`	Translates jargon and errors into plain Portuguese with non-tech analogies.
`daily-standup`	4-bullet "where we left off" briefing every session.
`os-self-test`	Verifies the OS is internally coherent.
`.github/`	PR + issue templates with vibe-coder dimension and CI workflow enforcing canon.

Active-help layer — helps you when something happens

Component	Activates when
`bug-triage-agent`	Build breaks, deploy crashes, "deu erro" / "quebrou".
`rollback-safe`	"desfaz isso" / "volta o que você fez".
`verify-build-works`	After every non-trivial edit, before commits, before push.
`usage-monitor`	"tô gastando muito" / "quanto custa" / weekly post-launch.
`launch-agent`	"vamos lançar" / "tá pronto pra mostrar".
`deploy-vercel-supabase`	"vamos publicar" / "como coloca no ar".
`first-100-users`	"ninguém tá usando" / post-launch acquisition.
`legal-compliance-agent`	Before public launch, before collecting user data, before charging.

See examples/nextjs-supabase-saas/ for the canonical layout the wizard generates from.

🧭 Core flow

Repository comprehension.
Friendly opening and user introduction.
Raw ideation: “Tell me about your project.”
Ideation polish and exactly 10 strategic questions.
Research plan approval.
Wave 1: competitor and market research.
Wave 2: red-team critique.
Wave 3: consolidation and BP writing.
Business Plan v0.0.1.
Human review.
Business Plan v0.0.2 with impact review.
Product Brief and Technical Plan.
14–20 sprint roadmap.
Prototype Lab with 3 HTML prototype directions.
Sprint 0 / Sprint 1 implementation.

The wizard intentionally prevents coding too early.

🧙 Project Genesis Wizard

The central workflow is defined in WIZARD.md.

It tells Claude to guide the user from raw idea to structured execution without skipping steps. The wizard is intentionally simple for the user and strict for the AI.

The user should only need to start with:

Me fale sobre teu projeto.

Behind the scenes, Claude is instructed to create and maintain:

docs/product/PRODUCT-BRIEF.md
docs/business/BUSINESS-PLAN.md
docs/technical/TECHNICAL-PLAN.md
docs/SPRINTS.md
CHANGELOG.md
session-log/
knowledge-base/
prototype-lab/

🤖 Agents

The .claude/agents/ layer defines specialized AI roles.

Core roles include:

Coordinator Agent — consolidates decisions and checks coherence.
Dev/Product Agent — reviews product and implementation decisions.
Research Agent — supports market, competitor, technical, and source-backed research.
Devil’s Advocate Agent — attacks weak assumptions and exposes contradictions.
Business Red Team Agent — challenges pricing, GTM, finance, and operational logic.
Technical Red Team Agent — challenges architecture, security, privacy, and implementation complexity.
Copywriter Agent — turns validated material into a strong BP/readable narrative.
Competitor Research Agent — finds competitors, narrows them down, and extracts strategic signals.
Market Research Agent — validates the niche using reports, official sources, benchmarks, and credible references.

🛠️ Skills

The .claude/skills/ layer contains reusable workflows.

Important skills include:

project-genesis — drives the full wizard.
sprint-management — opens/closes sprints and maintains sprint docs.
feature-scaffold — creates feature structure with rules and headers.
business-plan-impact-review — checks downstream impact after BP edits.
prototype-lab — creates three disposable HTML prototype directions.
privacy-audit — reviews privacy/LGPD-style risks.
secrets-scan — enforces secret scanning habits.
release-check — checks readiness before tagging/release.
decision-log — records why decisions were made.

📚 Documentation layers

Document	Purpose
`START-HERE.md`	First file Claude reads.
`WIZARD.md`	Full Project Genesis Wizard flow.
`docs/product/PRODUCT-BRIEF.md`	Operational product understanding.
`docs/business/BUSINESS-PLAN.md`	Business/investor/hackathon document.
`docs/technical/TECHNICAL-PLAN.md`	Stack, architecture, data, security, test plan.
`docs/SPRINTS.md`	Detailed sprint roadmap.
`CHANGELOG.md`	What changed by version.
`session-log/`	Why decisions were made.
`knowledge-base/`	Research outputs and source summaries.
`prototype-lab/`	Disposable HTML prototypes before building the real app.

🧪 Prototype Lab

Before building the production app, the wizard creates a separate prototype space:

prototype-lab/
├── index.html
├── prototype-a/
├── prototype-b/
├── prototype-c/
└── shared/

Rules:

Use plain HTML/CSS/JS.
Use the same mock data across all prototypes.
Make the prototypes visually distinct.
Match the personas and positioning from the Product Brief and Business Plan.
Do not mix prototype files with production source code.

🧱 Golden rules

These rules are intentionally strict:

Do not code before the wizard reaches the correct phase.
Keep separation of concerns.
Keep source-code files small, ideally under 200 lines.
Add clear headers to source files.
Use stable technology, not alpha/beta stacks.
Never hardcode secrets.
Document decisions in session logs.
Keep changelog and sprint docs updated.
Use red-team review before major strategic decisions.
Check downstream impact after Business Plan changes.

🧩 Stack packs

The repo is generic by default, but can be extended through stack packs:

stack-packs/
├── generic-saas/
├── nextjs-supabase-saas/
├── solana/
└── marketplace-saas/

The first-class target is a SaaS project, but the system can be adapted for web3, marketplaces, AI tools, legaltech, fintech, healthtech, and other product types.

🔐 Security posture

This repository is not a substitute for professional security review. It provides a baseline for safer AI-assisted development:

secrets scanning habits;
security review agents;
dependency and release checks;
privacy audit workflow;
documentation of security decisions;
optional references to security-focused external skills.

See SECURITY.md and docs/security-baseline.md.

🙌 Credits and upstream sources

This project is based on real-world AI-assisted development workflows and informed by several open-source repositories and public specs.

Primary references include:

Full attribution and source mapping:

👤 Author / maintainer

Created and maintained by Lucas Galvão.

Website: https://lucasgalvao.com.br
LinkedIn: https://www.linkedin.com/in/lucasgalvao/
X/Twitter: https://x.com/lg_lucas
GitHub: https://github.com/lglucas

Selected projects:

Complian.cc — https://complian.cc
ASH — https://ash.app.br
Tokenfy — https://tokenfy.me
Boring Co — https://github.com/lglucas/boringco (private/internal project reference; may not be publicly accessible)

📄 License

MIT License. See LICENSE.