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

.agentos/agents/AGENTS.md

@@ -0,0 +1,27 @@
+# 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
+- Researcher (Research Agent)
+  - templates/prompts/research.md
+
+
+Scripts
+- .agentos/scripts/preflight.sh
+- .agentos/scripts/postflight.sh
+- .agentos/scripts/create-spec.sh
+- .agentos/scripts/research.sh (dry-run stub)
+
+- .agentos/scripts/generate-tasks.sh
+- .agentos/scripts/implement-tasks.sh
+- .agentos/scripts/medusa-checks.sh (noop here)

.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.
+

.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
+

.agentos/product/decisions/README.md

@@ -0,0 +1 @@
+# Decisions (ADR Index)

.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.
+

.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)
+

.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"
+

.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"
+

.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
+

.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."
+

.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"
+

.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"
+

.agentos/scripts/research.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+info() { echo "[research] $*"; }
+warn() { echo "[research][warn] $*"; }
+
+TASK_INPUT=${1:-"Sample bug: Unexpected 404 on POST /todos when payload includes notes[]; using RR7 action and fetcher."}
+TOKENS=${TOKENS:-4000}
+
+info "DRY-RUN stub for Research Agent"
+info "Task: $TASK_INPUT"
+info "Tokens budget: $TOKENS"
+
+cat <<'EOF'
+Title
+- Research: Investigate issue and propose path forward
+
+Classification and Assumptions
+- Scope: Unknown (triage first)
+- Assumptions: React Router 7 loaders/actions in use; typed data flow expected
+
+Research Plan
+- Confirm RR7 action semantics for FormData arrays
+- Check server contract for /todos
+- Verify client request encoding (fetcher/form submit)
+- Identify authoritative docs using available tools (Context7, Exa/Perplexity, or browser/search MCP)
+
+Sources (with links and versions)
+- [1] TODO: https://reactrouter.com/ (v7) — action/form semantics
+- [2] TODO: https://developer.mozilla.org/ — FormData array encoding
+
+Findings and Tradeoffs
+- TODO bullets with [1][2] citations
+
+Recommendation
+- TODO single best path summary
+
+Repo Next Steps (checklist)
+- [ ] Target files: apps/todo-app/app/routes/*.tsx
+- [ ] Add/adjust contract tests under contracts/
+- [ ] Add loader/action type guards (+types)
+- [ ] Update plan/spec links
+
+Risks & Open Questions
+- Risk: behavior changes for existing consumers
+- [NEEDS CLARIFICATION: Is server expecting JSON or FormData?]
+EOF
+
+info "NOTE: This is a stub. Integrate with your agent runtime to call Context7, Exa/Perplexity, or browser/search MCP tools when available."

.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
+

.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
+

.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
+

.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
+

.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
+- ...
+

.agentos/templates/docs/research-usage.md

@@ -0,0 +1,38 @@
+# Research Agent — Usage Notes
+
+Purpose
+- Investigate bugs/implementation questions and produce evidence-backed recommendations aligned with the constitution and tech stack.
+
+Invocation (human-in-the-loop)
+- Use template: .agentos/templates/prompts/research.md
+- Provide a short task description and any relevant spec path under .agentos/specs/*
+- Depth defaults to pragmatic (2–3 primary sources). Ask for deeper dive if needed.
+
+Tooling Options (choose what’s available)
+- Step 1: resolve-library-id <library-name>
+- Step 2: get-library-docs <resolved-id> --topic <focus> --tokens 4000
+- Always call resolve-library-id before get-library-docs unless you have an exact Context7 ID.
+
+- General web search: Perplexity or Exa (exa_web_search + exa_web_view_page) to find authoritative docs/RFCs/READMEs
+- Browser/search MCP: chrome_get_web_content (snapshots), chrome_network_request (API docs), search_tabs_content (pivot within existing tabs)
+- No tools available: rely on local repository context and framework knowledge; cite local files and well-known framework behavior
+
+Browser/Search MCP Path (optional)
+- Use chrome_get_web_content for page snapshots
+- Use chrome_network_request for API docs
+- Use search_tabs_content to pivot within already-open tabs
+
+Safety
+- Never print secrets; use placeholders like {{API_TOKEN}} / {{SECRET_NAME}}.
+- Prefer read-only commands; ask for confirmation before risky actions.
+
+Dry-Run Validation
+- Given a sample bug report, outputs MUST include:
+  - Classification, Research Plan, 2–3 authoritative Sources, Findings, Recommendation,
+    Repo Next Steps (checklist), Risks & Open Questions.
+- Citations must resolve and match claims.
+
+Notes
+- Prefer RR7 primitives, Tailwind, workspace conventions in examples.
+- Mark gaps with [NEEDS CLARIFICATION: …].
+- Keep outputs skimmable for PRs/issues.

.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
+