feat(agentos): bootstrap Lambda AgentOS v0.1 skeleton (standards, constitution, prompts, scripts, CI)

codegen-sh[bot] · jaruesink · codegen-sh[bot] · commit 03e87bd7b06e · 2025-09-21T00:15:19.000Z
Includes:
- .agentos/standards (tech-stack, code-style, best-practices, medusa-guidelines)
- .agentos/product (mission, architecture, roadmap, decisions/)
- .agentos/memory/constitution.md (non-negotiable gates)
- .agentos/templates (docs + prompts)
- .agentos/scripts (preflight/postflight/spec helpers)
- .agentos/agents/AGENTS.md
- .github/workflows/lambda-agentos.yml + PR template

Co-authored-by: Jake Ruesink &lt;jaruesink@gmail.com&gt;
diff --git a/.agentos/agents/AGENTS.md b/.agentos/agents/AGENTS.md
@@ -0,0 +1,23 @@
+# Lambda AgentOS — Agents (v0.1)
+
+- Product Spec Agent
+  - templates/prompts/specify.md
+- Technical Planner
+  - templates/prompts/plan.md
+- Task Orchestrator
+  - templates/prompts/tasks.md
+- Implementer
+  - templates/prompts/implement.md
+- Reviewer (PR Gatekeeper)
+  - templates/prompts/review.md
+- Medusa Integrator
+  - templates/prompts/medusa-plugin.md
+
+Scripts
+- .agentos/scripts/preflight.sh
+- .agentos/scripts/postflight.sh
+- .agentos/scripts/create-spec.sh
+- .agentos/scripts/generate-tasks.sh
+- .agentos/scripts/implement-tasks.sh
+- .agentos/scripts/medusa-checks.sh (noop here)
+
diff --git a/.agentos/memory/constitution.md b/.agentos/memory/constitution.md
@@ -0,0 +1,25 @@
+# Lambda AgentOS Constitution (v0.1)
+
+Articles (non‑negotiables)
+
+I. Simplicity Gate
+- Prefer framework primitives; no custom abstractions until repeated ≥3×.
+
+II. Contract‑first
+- Define contracts/tests before source code; keep failing tests visible until satisfied.
+
+III. Typed data flow
+- Route loaders/actions and components must be typed end‑to‑end; no `any`/`unknown` leaks.
+
+IV. Separation of concerns
+- UI never calls DB directly; data access behind services/APIs. (In this repo, mock services only.)
+
+V. Spec traceability
+- Every change references a spec path under .agentos/specs; PR template must link it.
+
+VI. Drift control
+- If contracts change, regenerate tasks and update plan/spec; do not “patch” code silently.
+
+VII. Review gates
+- Pre-flight must pass before implementation; post-flight must pass before merge.
+
diff --git a/.agentos/product/architecture.md b/.agentos/product/architecture.md
@@ -0,0 +1,9 @@
+# Architecture Overview
+
+- Monorepo (Turborepo + Bun)
+- React Router 7 app in apps/* with file-based route modules
+- Shared packages in packages/* with proper exports
+- Styling via Tailwind; component patterns via shadcn/ui (optional)
+- Testing via Vitest; lint via Biome; typechecking via tsc
+- CI via GitHub Actions; see .github/workflows
+
diff --git a/.agentos/product/decisions/README.md b/.agentos/product/decisions/README.md
@@ -0,0 +1 @@
+# Decisions (ADR Index)
diff --git a/.agentos/product/mission.md b/.agentos/product/mission.md
@@ -0,0 +1,4 @@
+# Mission
+
+Provide a high-quality React Router 7 starter showcasing route modules, loaders/actions, type-safe data flows, Tailwind styling, and workspace ergonomics suitable for AI-assisted, spec-driven development.
+
diff --git a/.agentos/product/roadmap.md b/.agentos/product/roadmap.md
@@ -0,0 +1,6 @@
+# Roadmap (Starter)
+
+- 001: Add Lambda AgentOS skeleton (this PR)
+- 002: Example feature spec demonstrating contract-first data flow
+- 003: Optional Medusa integration sample (service API stub + UI)
+
diff --git a/.agentos/scripts/create-spec.sh b/.agentos/scripts/create-spec.sh
@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: ./create-spec.sh "Feature Title"
+
+TITLE_RAW=${1:-sample-feature}
+TITLE_SLUG=$(echo "$TITLE_RAW" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g; s/^-|-$//g')
+NEXT_NUM=$(printf "%03d" 1)
+
+# Compute next number by counting existing dirs
+if [ -d .agentos/specs ]; then
+  COUNT=$(find .agentos/specs -maxdepth 1 -mindepth 1 -type d | wc -l | xargs)
+  NEXT_NUM=$(printf "%03d" $((COUNT + 1)))
+fi
+
+DIR=".agentos/specs/${NEXT_NUM}-${TITLE_SLUG}"
+mkdir -p "$DIR/contracts"
+
+cp .agentos/templates/docs/spec-template.md "$DIR/spec.md"
+cp .agentos/templates/docs/plan-template.md "$DIR/plan.md"
+cp .agentos/templates/docs/tasks-template.md "$DIR/tasks.md"
+
+echo "Created spec at $DIR"
+
diff --git a/.agentos/scripts/generate-tasks.sh b/.agentos/scripts/generate-tasks.sh
@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: ./generate-tasks.sh PATH_TO_SPEC_DIR
+SPEC_DIR=${1:-}
+if [ -z "$SPEC_DIR" ]; then
+  echo "Usage: $0 .agentos/specs/NNN-feature" >&2
+  exit 1
+fi
+
+# Here we would invoke an agent to read plan.md and produce tasks.md.
+# For v0.1, we ensure the file exists and print a hint.
+if [ ! -f "$SPEC_DIR/plan.md" ]; then
+  echo "Missing $SPEC_DIR/plan.md" >&2
+  exit 1
+fi
+
+[ -f "$SPEC_DIR/tasks.md" ] || cp .agentos/templates/docs/tasks-template.md "$SPEC_DIR/tasks.md"
+echo "Tasks prepared at $SPEC_DIR/tasks.md"
+
diff --git a/.agentos/scripts/implement-tasks.sh b/.agentos/scripts/implement-tasks.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Usage: ./implement-tasks.sh PATH_TO_SPEC_DIR
+SPEC_DIR=${1:-}
+if [ -z "$SPEC_DIR" ]; then
+  echo "Usage: $0 .agentos/specs/NNN-feature" >&2
+  exit 1
+fi
+
+.agentos/scripts/preflight.sh
+
+# Placeholder: v0.1 does not auto‑apply code changes.
+# Implementers follow tasks.md and commit step-by-step.
+
+.agentos/scripts/postflight.sh
+
diff --git a/.agentos/scripts/medusa-checks.sh b/.agentos/scripts/medusa-checks.sh
@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+echo "[medusa-checks] This repo is frontend-only. For Medusa projects, implement container registration checks, event/subscriber validation, and version pinning here."
+
diff --git a/.agentos/scripts/postflight.sh b/.agentos/scripts/postflight.sh
@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+info() { echo "[postflight] $*"; }
+
+info "Running lint/typecheck/build/tests via Turbo"
+
+bun run turbo lint
+bun run turbo typecheck
+bun run turbo build
+bun run turbo test:ci
+
+info "Post-flight checks complete"
+
diff --git a/.agentos/scripts/preflight.sh b/.agentos/scripts/preflight.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+info() { echo "[preflight] $*"; }
+warn() { echo "[preflight][warn] $*"; }
+
+info "Starting pre-flight checks"
+
+# Tooling
+if command -v bun >/dev/null 2>&1; then bun --version || true; else warn "bun not found"; fi
+if command -v turbo >/dev/null 2>&1; then turbo --version || true; else warn "turbo not found (will use bun run turbo)"; fi
+
+# Linting tool presence (Biome or ESLint)
+if bunx --help >/dev/null 2>&1; then
+  (bunx biome --version >/dev/null 2>&1 && info "Biome available") || warn "Biome not found"
+else
+  warn "bunx not available; skipping biome check"
+fi
+
+# Prisma (optional)
+if command -v prisma >/dev/null 2>&1; then
+  info "Checking Prisma connectivity"
+  prisma validate || warn "prisma validate failed (ok if no DB in this repo)"
+else
+  info "No Prisma in this repo; skipping DB checks"
+fi
+
+# Frontend build sanity (best-effort)
+if [ -f "package.json" ]; then
+  info "Workspace sanity: turbo graph"
+  (bun run turbo run build --dry-run >/dev/null 2>&1 && info "turbo dry-run ok") || warn "turbo dry-run failed"
+fi
+
+info "Pre-flight checks complete"
+
diff --git a/.agentos/standards/best-practices.md b/.agentos/standards/best-practices.md
@@ -0,0 +1,10 @@
+# Best Practices (Global Standard)
+
+- Small vertical slices: spec → plan → tasks → implement → review
+- TDD bias: write contracts/tests first; keep failing tests visible
+- Avoid speculative architecture until needed ≥ 3 times
+- Document decisions as ADRs in .agentos/product/decisions
+- Keep specs living; update spec/plan when reality changes
+- Prefer composition over inheritance; data flows explicit
+- Accessibility: aim for WCAG 2.1 AA; semantic markup; focus states
+
diff --git a/.agentos/standards/code-style.md b/.agentos/standards/code-style.md
@@ -0,0 +1,12 @@
+# Code Style (Global Standard)
+
+- TypeScript strict; no implicit any
+- Max line width 120; 2-space indent
+- Biome (or ESLint + Prettier) required
+- Named exports preferred; default exports allowed where idiomatic
+- React: function components, hooks > classes, narrow props
+- File naming: kebab-case for files; PascalCase for components
+- Imports: absolute aliases per package tsconfig; group std/ext/local
+- Commit style: conventional commits (feat, fix, chore, docs, refactor, ci)
+- PR etiquette: small diffs; cite spec path in description
+
diff --git a/.agentos/standards/medusa-guidelines.md b/.agentos/standards/medusa-guidelines.md
@@ -0,0 +1,9 @@
+# Medusa Guidelines (Org Standard)
+
+- Prefer modules/plugins with explicit container registrations
+- Expose services with clear interfaces; avoid leaking repositories to UI
+- Use events/subscribers for side-effects; keep services pure
+- Maintain OpenAPI contracts for public endpoints
+- Provide admin UI hooks via extension points; avoid tight coupling
+- Version pinning for plugins; update with migration notes
+
diff --git a/.agentos/standards/tech-stack.md b/.agentos/standards/tech-stack.md
@@ -0,0 +1,19 @@
+# Lambda AgentOS — Tech Stack (Global Standard)
+
+This standard defines our default stack used across projects and adopted by Lambda AgentOS.
+
+- Language: TypeScript (strict), Node >= 20.11
+- Frontend: React 19, React Router 7 (route modules, loaders/actions, +types)
+- Styling: Tailwind CSS (utility-first), shadcn/ui where applicable
+- Build/Workspace: Turborepo, Bun, Biome (or ESLint+Prettier), Vitest
+- Data: Prisma + Postgres (where backend exists)
+- Commerce: MedusaJS (modules, services, events, subscribers)
+- API Contracts: OpenAPI (YAML) for server endpoints; contract-first where possible
+- CI: GitHub Actions (lint, typecheck, build, tests, drift checks)
+
+Non-negotiables
+- Prefer framework primitives first (React Router loaders/actions; simple composition)
+- Test-first order: contracts → integration/e2e → unit → source
+- No direct DB from UI; UI consumes typed contracts
+- Keep specs and docs close to code: see .agentos/specs and .agentos/product
+
diff --git a/.agentos/templates/docs/plan-template.md b/.agentos/templates/docs/plan-template.md
@@ -0,0 +1,20 @@
+# Implementation Plan Template
+
+## Architecture & Decisions
+- Chosen stack (RR7 routes, loaders/actions; Tailwind; any service layer)
+- Contracts first (OpenAPI, types)
+- Data model diffs (if any)
+
+## Phase -1: Gates
+- [ ] Simplicity Gate (≤3 projects, no future-proofing)
+- [ ] Anti-Abstraction Gate (use framework primitives)
+- [ ] Test-First Gate (contracts/tests before impl)
+
+## Deliverables
+- contracts/api.yaml
+- data-model.prisma (if applicable)
+- quickstart.md (validation scenarios)
+
+## Risks & Mitigations
+- ...
+
diff --git a/.agentos/templates/docs/spec-template.md b/.agentos/templates/docs/spec-template.md
@@ -0,0 +1,21 @@
+# Feature Spec Template
+
+## Summary
+What are we building and why (user stories, outcomes)? Avoid implementation details.
+
+## Scope & Non-Goals
+- In scope:
+- Out of scope:
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Open Questions
+- [NEEDS CLARIFICATION: ]
+
+## Review & Acceptance Checklist
+- [ ] Requirements are unambiguous and testable
+- [ ] No unresolved [NEEDS CLARIFICATION]
+- [ ] Success criteria measurable
+
diff --git a/.agentos/templates/docs/tasks-template.md b/.agentos/templates/docs/tasks-template.md
@@ -0,0 +1,20 @@
+# Tasks Template
+
+Derive tasks from plan and contracts. Mark parallelizable with [P].
+
+## Inputs
+- plan.md
+- contracts/
+- data-model.prisma (if applicable)
+
+## Tasks
+1. [ ] [P] Generate/validate contracts
+2. [ ] Scaffold route(s) and loaders/actions
+3. [ ] Implement UI with Tailwind/shadcn
+4. [ ] Wire service calls to contracts
+5. [ ] Tests: contract → integration → e2e → unit
+
+## Gates
+- [ ] Pre-flight passed
+- [ ] Post-flight passed
+
diff --git a/.agentos/templates/prompts/implement.md b/.agentos/templates/prompts/implement.md
@@ -0,0 +1,9 @@
+You are the Implementer for Lambda AgentOS.
+Goal: Execute tasks with test-first ordering and frequent commits.
+
+Instructions
+- Honor constitution gates; do not bypass pre/post-flight
+- File creation order: contracts → tests → source
+- Keep diffs small; reference spec path in commit messages
+- After completion, run post-flight and prepare PR notes
+
diff --git a/.agentos/templates/prompts/medusa-plugin.md b/.agentos/templates/prompts/medusa-plugin.md
@@ -0,0 +1,8 @@
+You are the Medusa Integrator for Lambda AgentOS.
+Goal: Scaffold/wire Medusa modules/plugins in Medusa repos; in this frontend repo, generate stubs or notes only.
+
+Instructions
+- When in a Medusa repo: create service modules, register in container, define events/subscribers, add tests
+- When in a frontend-only repo: generate API contracts and client adapters; avoid server code here
+- Validate plugin versions; produce migration notes if needed
+
diff --git a/.agentos/templates/prompts/plan.md b/.agentos/templates/prompts/plan.md
@@ -0,0 +1,10 @@
+You are the Technical Planner for Lambda AgentOS.
+Goal: Translate spec into an implementation plan with enforceable gates.
+
+Instructions
+- Use .agentos/templates/docs/plan-template.md
+- Choose RR7 primitives, Tailwind, and workspace conventions
+- If backend is needed, describe contracts and mock services for this repo
+- Generate contracts/api.yaml and quickstart.md
+- Save to .agentos/specs/NNN-feature-name/plan.md
+
diff --git a/.agentos/templates/prompts/review.md b/.agentos/templates/prompts/review.md
@@ -0,0 +1,9 @@
+You are the Reviewer (PR Gatekeeper) for Lambda AgentOS.
+Goal: Enforce constitution and acceptance checklists before merge.
+
+Instructions
+- Verify preflight and postflight succeeded
+- Confirm spec/plan/tasks are linked and updated
+- Check contracts/tests first; ensure drift is addressed via spec, not code hacks
+- Leave actionable comments; request changes if gates fail
+
diff --git a/.agentos/templates/prompts/specify.md b/.agentos/templates/prompts/specify.md
@@ -0,0 +1,10 @@
+You are the Product Spec Agent for Lambda AgentOS.
+Goal: Convert a feature idea into an unambiguous spec.
+
+Instructions
+- Focus on WHAT/WHY; avoid HOW
+- Use .agentos/templates/docs/spec-template.md
+- Mark ambiguities with [NEEDS CLARIFICATION: question]
+- Produce acceptance criteria and success metrics
+- Save to .agentos/specs/NNN-feature-name/spec.md
+
diff --git a/.agentos/templates/prompts/tasks.md b/.agentos/templates/prompts/tasks.md
@@ -0,0 +1,9 @@
+You are the Task Orchestrator for Lambda AgentOS.
+Goal: Convert plan and contracts into an executable, parallelizable task list.
+
+Instructions
+- Use .agentos/templates/docs/tasks-template.md
+- Read plan.md, contracts/, and data-model (if present)
+- Mark parallel groups with [P]; add dependencies explicitly
+- Save to .agentos/specs/NNN-feature-name/tasks.md
+
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -0,0 +1,15 @@
+### Summary
+Briefly describe the change.
+
+### Spec Link
+- Spec path: `.agentos/specs/<NNN-feature>/` (paste exact path)
+
+### Pre-/Post-flight
+- [ ] Ran `.agentos/scripts/preflight.sh`
+- [ ] Ran `.agentos/scripts/postflight.sh`
+
+### Notes
+- Mention any ADRs updated in `.agentos/product/decisions`
+
+Requested by: Jake Ruesink
+
diff --git a/.github/workflows/lambda-agentos.yml b/.github/workflows/lambda-agentos.yml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,4 @@ @@
 +# Mission
++
 +Provide a high-quality React Router 7 starter showcasing route modules, loaders/actions, type-safe data flows, Tailwind styling, and workspace ergonomics suitable for AI-assisted, spec-driven development.
++