{"id":49655660,"url":"https://github.com/shadowdevcode/ai-product-os","last_synced_at":"2026-05-06T09:05:35.641Z","repository":{"id":344603360,"uuid":"1175889877","full_name":"shadowdevcode/ai-product-os","owner":"shadowdevcode","description":"A simulated, end-to-end product development organization where specialized AI agents collaborate to take an idea from raw hypothesis to deployed, instrumented product — following the same rigor as a real product team.","archived":false,"fork":false,"pushed_at":"2026-04-30T18:03:31.000Z","size":2281,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T19:15:32.816Z","etag":null,"topics":["ai-agents","claude-ai","claude-code","productivity","productmanagement"],"latest_commit_sha":null,"homepage":"https://ai-product-os-493e.vercel.app/","language":"TypeScript","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/shadowdevcode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-08T10:19:41.000Z","updated_at":"2026-04-30T18:03:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shadowdevcode/ai-product-os","commit_stats":null,"previous_names":["shadowdevcode/ai-product-os"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shadowdevcode/ai-product-os","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowdevcode%2Fai-product-os","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowdevcode%2Fai-product-os/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowdevcode%2Fai-product-os/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowdevcode%2Fai-product-os/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shadowdevcode","download_url":"https://codeload.github.com/shadowdevcode/ai-product-os/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shadowdevcode%2Fai-product-os/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32686272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-06T08:33:17.875Z","status":"ssl_error","status_checked_at":"2026-05-06T08:33:17.221Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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-agents","claude-ai","claude-code","productivity","productmanagement"],"created_at":"2026-05-06T09:05:34.666Z","updated_at":"2026-05-06T09:05:35.632Z","avatar_url":"https://github.com/shadowdevcode.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Product Operating System\n\nA simulated, end-to-end product development organization where specialized AI agents collaborate to take an idea from raw hypothesis to deployed, instrumented product — following the same rigor as a real product team.\n\n**Who this is for:** Product Managers, indie founders, and ICPs who want to ship AI-assisted products faster without skipping the parts that matter — research, architecture review, QA, metrics, and learning.\n\n\u003e **Live:** [ai-product-os-493e.vercel.app](https://ai-product-os-493e.vercel.app/) | Built and operated with [Claude Code](https://claude.ai/code). You need Claude Code to run the slash commands.\n\u003e\n\u003e Deploy note: `ai-product-os-493e` is the current landing Vercel project. MoneyMirror was a separate Vercel project in earlier cycles; its legacy app code has been removed from this monorepo and its archived Vercel project is no longer linked to this GitHub repo.\n\n---\n\n## Quick Navigation\n\n| What you're looking for                  | Where to find it                                                         |\n| ---------------------------------------- | ------------------------------------------------------------------------ |\n| Active project status, stage, blockers   | [`project-state.md`](project-state.md)                                   |\n| Product ideas and issue definitions      | [`experiments/ideas/issue-NNN.md`](experiments/ideas/)                   |\n| Market research and problem exploration  | [`experiments/exploration/exploration-NNN.md`](experiments/exploration/) |\n| PRDs, UX specs, architecture plans       | [`experiments/plans/plan-NNN.md`](experiments/plans/)                    |\n| QA, code review, metrics, deploy results | [`experiments/results/`](experiments/results/)                           |\n| Demo scripts and presentations           | [`experiments/demos/`](experiments/demos/)                               |\n| Built app codebases                      | [`apps/[project-name]/`](apps/)                                          |\n| Pipeline command instructions            | [`commands/`](commands/)                                                 |\n| Agent role definitions                   | [`agents/`](agents/)                                                     |\n| Engineering and product knowledge base   | [`knowledge/`](knowledge/)                                               |\n| Quality gate rules and stage progression | [`system-orchestrator.md`](system-orchestrator.md)                       |\n| Command execution framework              | [`command-protocol.md`](command-protocol.md)                             |\n\n---\n\n## Projects Built\n\n| Issue | App                                                  | What It Does                                                                                                                                      | Stack                                                    | Status   |\n| ----- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | -------- |\n| 002   | —                                                    | Gmail → WhatsApp daily digest summarizer                                                                                                          | Next.js, Supabase, Gemini, Twilio                        | Archived |\n| 003   | [finance-advisor](apps/finance-advisor/)             | AI personal finance advisor                                                                                                                       | Next.js, Supabase, Gemini                                | Complete |\n| 004   | [clarity](apps/clarity/)                             | PM to-do list with AI task categorization                                                                                                         | Next.js, Neon, Gemini                                    | Complete |\n| 005   | [smb-bundler](apps/smb-bundler/)                     | Feature bundle + value-based pricing engine for B2B SaaS PMs                                                                                      | Next.js, Neon, Gemini                                    | Complete |\n| 006   | [ozi-reorder](apps/ozi-reorder/)                     | Reorder reminder experiment for dark-store baby essentials (50/50 test vs. control, 7 PostHog events)                                             | Next.js, Neon, PostHog                                   | Complete |\n| 007   | [ozi-insights](apps/ozi-insights/)                   | Synthetic Freshdesk support data for order reliability research (30 tickets, grounded in Play Store)                                              | Data workspace                                           | Explored |\n| 008   | [nykaa-personalisation](apps/nykaa-personalisation/) | Hyper-personalized discovery feed (affinity + intent scoring, 10 PostHog events, 5 API routes)                                                    | Next.js, Neon, PostHog                                   | Archived |\n| 009   | money-mirror                                         | AI personal finance coach — parses Indian bank + credit card PDFs, reveals perception gap, delivers consequence-first nudges. Weekly recap email. | Next.js 16, Neon Auth, Neon DB, Gemini 2.5 Flash, Resend | Archived |\n| 013   | [research-copilot](apps/research-copilot/)           | Chat-first PM research workspace with plan approval, visible tool orchestration, cited findings, and Markdown export.                             | Next.js 16, Neon Postgres, OpenRouter, PostHog           | T0       |\n| —     | [landing](apps/landing/)                             | Framework landing page showcasing pipeline, agents, and shipped products                                                                          | Next.js, Tailwind CSS                                    | Live     |\n\nEach issue number maps directly across all folders: `experiments/ideas/issue-NNN.md`, `experiments/exploration/exploration-NNN.md`, `experiments/plans/plan-NNN.md`, and `experiments/results/*-NNN.md`.\n\n---\n\n## The 12-Step Pipeline\n\nThe OS enforces a sequential pipeline with quality gates. A stage cannot start until the previous stage passes.\n\n| #   | Command         | Agent                                    | Output                                               |\n| --- | --------------- | ---------------------------------------- | ---------------------------------------------------- |\n| 1   | `/create-issue` | Research Agent                           | Structured opportunity brief                         |\n| 2   | `/explore`      | Research Agent                           | Market validation, recommendation                    |\n| 3   | `/create-plan`  | Product + Design + Backend/DB Architects | PRD, UX, architecture, DB schema                     |\n| 4   | `/execute-plan` | Frontend + Backend Engineers             | Working app codebase                                 |\n| 5   | `/deslop`       | Deslop Agent                             | Clean, comment-free code                             |\n| 6   | `/review`       | Code Review Agent                        | Critical issues list (blocks until fixed)            |\n| 7   | `/peer-review`  | Peer Review Agent                        | Adversarial architecture review                      |\n| 8   | `/qa-test`      | QA Agent                                 | Reliability and edge-case test results               |\n| 9   | `/metric-plan`  | Analytics Agent                          | North Star, funnels, ground-truth queries            |\n| 10  | `/deploy-check` | Deploy Agent                             | Production readiness sign-off                        |\n| 11  | `/postmortem`   | Learning Agent                           | Root cause analysis of pipeline failures             |\n| 12  | `/learning`     | Learning Agent                           | Engineering rules extracted → knowledge base updated |\n\n**Utility commands** (run anytime):\n\n- `/docs` — Generate `CODEBASE-CONTEXT.md` for the active app\n- `/explain` — Deep-dive on a concept, pattern, or error\n- `/linear-bind` — Bind the active repo issue to a Linear team/project (auto-runs at end of `/create-issue`)\n- `/linear-sync [mode]` — Mirror repo artifacts into Linear; modes: `issue`, `plan`, `status`, `release`\n- `/linear-brief` — Read-only summary of the current Linear state; use before reviews or standups\n- `/linear-close` — Finalize and archive the Linear project after `/learning`\n\n---\n\n## Knowledge Base\n\nThe system gets smarter with every cycle. After each `/learning` run, insights from postmortems are extracted into durable rules:\n\n- [`knowledge/engineering-lessons.md`](knowledge/engineering-lessons.md) — Technical rules (e.g., fan-out cron, pagination bounds, telemetry resilience)\n- [`knowledge/product-lessons.md`](knowledge/product-lessons.md) — Product patterns and anti-patterns\n- [`knowledge/prompt-library.md`](knowledge/prompt-library.md) — Refined agent prompts extracted from what worked\n- [`knowledge/coding-standards.md`](knowledge/coding-standards.md) — TypeScript, Next.js, Supabase/Neon standards\n- [`knowledge/architecture-guide.md`](knowledge/architecture-guide.md) — Default system architecture patterns\n- [`knowledge/analytics-framework.md`](knowledge/analytics-framework.md) — PostHog event schema and funnel design\n\nEvery agent reads the knowledge base before executing — preventing the same class of mistake from appearing twice.\n\n---\n\n## Linear PM Layer\n\nLinear is an optional PM-facing layer on top of the repo workflow.\n\nThe source of truth remains in this repository:\n\n- `project-state.md` is the canonical workflow state\n- `experiments/` contains the canonical issue, exploration, plan, and result artifacts\n- `experiments/linear-sync/` stores durable Linear sync identities per issue\n- `commands/` defines the execution contracts\n\nLinear exists to improve:\n\n- prioritization\n- roadmap visibility\n- blocker communication\n- task tracking from execution manifests\n- release and closeout visibility\n\nRecommended usage:\n\n| Pipeline stage                        | Linear command             | What it does                               |\n| ------------------------------------- | -------------------------- | ------------------------------------------ |\n| `/create-issue`                       | (auto) bind + `sync issue` | Creates Linear project; syncs issue brief  |\n| `/create-plan`                        | `/linear-sync plan`        | Publishes PRD summary + child tasks        |\n| `/review`, `/peer-review`, `/qa-test` | `/linear-sync status`      | Reflects gate pass/fail, surfaces blockers |\n| `/deploy-check`                       | `/linear-sync release`     | Attaches PR link and release notes         |\n| `/learning`                           | `/linear-close`            | Marks project complete, archives it        |\n\nIf Linear is unavailable, the Linear utility command should fail explicitly. The 12-step pipeline remains usable because Linear is not the workflow engine.\n\n---\n\n## Getting Started (Forking This Repo)\n\n1. **Check the current state** — read [`project-state.md`](project-state.md) to see what stage the system is at and which issue is active\n2. **Pick an idea** — browse [`experiments/ideas/`](experiments/ideas/) for context on past issues, or create a new one with `/create-issue`\n3. **Run commands sequentially** — pass the command file from [`commands/`](commands/) to Claude Code (e.g., paste `commands/create-issue.md` content and follow it)\n4. **Read the knowledge base first** — every command in the pipeline reads all files in [`knowledge/`](knowledge/) before generating output to avoid repeating past mistakes\n5. **Track gates, not just progress** — check `project-state.md` after each command; blocked = do not proceed\n6. **Validate repo changes** — run `bun install` and `bun run validate` from the repo root before accepting agent work\n\n**Default tech stack** (used across all apps):\n\n- Frontend: Next.js 16+ (App Router), TypeScript strict, Tailwind CSS 4+\n- Backend: Next.js API Routes, Neon DB (`@neondatabase/serverless`) or Supabase\n- AI: Google Gemini 2.5 Flash/Pro via `@google/genai` with structured outputs\n- Analytics: PostHog (`posthog-js` + `posthog-node`)\n- Hosting: Vercel\n\n**Environment setup per app:**\n\n```bash\nbun install\ncd apps/[project-name]\ncp .env.local.example .env.local   # fill in your keys\nbun run dev\n```\n\nEach app includes a `schema.sql` (idempotent) that must be applied in your database editor before first run.\n\n---\n\n## The Human PM Role\n\nAgents execute but do not replace judgment. The human PM is responsible for:\n\n- Deciding which ideas to pursue\n- Evaluating agent outputs at each stage\n- Overriding blocked quality gates when the tradeoff is justified\n- Making final product and architectural decisions\n- Approving releases\n\n---\n\n## Repository Structure\n\n```\n/agents                    # Agent role definitions (one file per role)\n/commands                  # Pipeline command instructions (one file per command)\n/knowledge                 # Shared intelligence: standards, lessons, prompts\n/experiments\n  /ideas                   # Issue briefs (issue-NNN.md)\n  /exploration             # Market validation outputs (exploration-NNN.md)\n  /plans                   # PRDs, UX, architecture, DB schema (plan-NNN.md)\n  /results                 # QA, reviews, metrics, deploy artifacts (*-NNN.md)\n  /demos                   # Demo scripts and presentations\n/apps                      # Built codebases (one folder per project)\n  /[project-name]\n    src/app/               # Next.js App Router pages and API routes\n    src/components/        # UI components\n    src/lib/               # Utilities, DB clients, AI helpers\n    schema.sql             # Idempotent DB schema\n    CODEBASE-CONTEXT.md    # Auto-generated docs (via /docs command)\n    README.md              # Setup and run instructions\n    .env.local.example     # Required env vars (no secrets)\nproject-state.md           # Live runtime memory — always check this first\nsystem-orchestrator.md     # Quality gate rules and stage progression\ncommand-protocol.md        # How commands load context and update state\n```\n\n---\n\n## System Evolution\n\nThis OS isn't static — it improves with every cycle. Full history in [`CHANGELOG.md`](CHANGELOG.md).\n\n| Phase  | What Changed                                                                                                                                                                                                                                                                                                | PM Decision                                                                                                                                       |\n| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **v0** | Manual pipeline, no enforcement                                                                                                                                                                                                                                                                             | Proved the 12-step concept works end-to-end                                                                                                       |\n| **v1** | Quality gates, knowledge base, 5 shipped products                                                                                                                                                                                                                                                           | Each postmortem generated rules that prevented the same class of failure in the next cycle                                                        |\n| **v2** | Developer tooling (husky, prettier, enforcement scripts), test infrastructure (Vitest + shared mocks), progressive disclosure (.claude/rules/), landing page                                                                                                                                                | Finalized with Nykaa Hyper-Personalization (issue-008). AI Product OS v2 is now feature-complete.                                                 |\n| **v3** | MoneyMirror (issue-009): most complex pipeline cycle — Neon Auth, multi-bank PDF parsing, credit card flows, perception gap dashboard, weekly recap email. Phase 2 adds 3-tab dashboard, statement library, month picker, upload labels, multi-account. Linear PM layer + real-time feedback capture added. | First cycle requiring live DB migration, production smoke, and Vercel runtime fix before passing deploy-check. 7 new engineering rules extracted. |\n\n---\n\n_Build faster. Learn systematically. Fail safely._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowdevcode%2Fai-product-os","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshadowdevcode%2Fai-product-os","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshadowdevcode%2Fai-product-os/lists"}