lean-router

name

lean-router

description

The entry point and orchestrator for the Lean Agentic AI Skills. Use this skill FIRST whenever the user asks anything sustainability-, carbon-, energy-, or efficiency-related about their software, website, cloud, AI pipeline, or wants a green audit, report, deck, or dashboard — even if they don't name a specific skill. Also use it when the user's request spans multiple steps ("audit X and make me a presentation"), when it's unclear which sustainability skill applies, or when the user mentions reducing compute or cloud cost. This skill classifies the request, selects and sequences the right suite skills, right-sizes model effort per step, and merges findings between steps.

Green Router

The orchestrator for the Lean Agentic AI Skills. It does one job well: turn a user request into a pipeline of single-purpose sustainability skills, wired together through the shared lean-findings.json contract.

The composition model (read this first)

Every skill in the suite is either a producer, a consumer, or a transformer of the shared findings format defined in schemas/lean-findings.schema.json (sibling directory to this suite's skills; a copy ships in references/lean-findings.schema.json).

• Producers (audits): web-carbon-audit, cloud-waste-audit, green-code-review, agentic-loop-auditor, ... Each emits one lean-findings.json.
• Consumers (outputs): lean-deck-builder, lean-report-writer, sci-receipt, lean-dashboard. Each accepts one or more findings files.
• Transformers: merge, filter, or re-rank findings between the two.

Because producers and consumers only speak through the contract, any audit can feed any output format. The router's job is picking the chain, not doing the work.

Routing procedure

1. Classify the request along two axes:

   • Subject: website | codebase | cloud account | AI/LLM pipeline | CI pipeline | database | architecture design | document/output only
   • Intent: audit (find problems) | generate (build something green) | report (communicate findings) | schedule (time-shift work) | mixed

2. Select the pipeline. Common shapes:

   User says	Pipeline
   "Is my website green?"	web-carbon-audit → inline summary
   "Audit our site and make a deck for leadership"	web-carbon-audit → lean-deck-builder
   "Audit cloud spend and our website, one report"	cloud-waste-audit + web-carbon-audit → merge → lean-report-writer
   "Are our instances oversized?"	right-size-compute (+ container-density-audit if k8s)
   "Should this VM be a Lambda?"	vm-to-serverless-advisor
   "Storage costs keep growing"	storage-lifecycle-audit (+ data-minimization-designer for the greenfield fix)
   "The database is slow and hot"	db-efficiency-audit (→ caching-strategy-designer if uncached repeats found)
   "CI takes forever"	lean-ci-audit
   "Make our chatbot cheaper/greener"	model-right-sizer + prompt-carbon-optimizer + llm-cache-designer → sci-receipt
   "Our agent burns tokens"	agentic-loop-auditor → sci-receipt
   "Where should we deploy / when should batches run?"	region-selector / carbon-aware-scheduler
   "Track findings over time"	existing findings files → lean-dashboard
   "This will be printed for the board"	any output → print-conscious-formatter
   "Training is slow/expensive"	training-efficiency-audit (+ carbon-aware-scheduler pairing)
   "Our RAG answers cost too much"	rag-pipeline-optimizer → sci-receipt
   "The app drains battery/data"	lean-mobile-audit
   "We stream a lot of video"	video-streaming-optimizer
   "Observability bill keeps growing"	logging-telemetry-audit
   "Did we improve since last audit?"	findings-diff (→ lean-dashboard for the trend)
   "Fail the build if we regress"	lean-regression-gate setup
   "We want actual carbon numbers"	impact-framework-bridge
   "Set efficiency targets for teams"	carbon-budget-designer
   "Our Spark/dbt pipelines are heavy"	data-pipeline-audit
   "Why is our JavaScript bundle huge?"	js-bundle-audit
   "Clients hammer our API"	api-efficiency-audit
   "Image generation costs too much"	genai-media-optimizer → sci-receipt
   "Add an eco mode to the product"	demand-shaping-designer
   "Should we refresh the laptop fleet?"	hardware-lifecycle-advisor
   "Put the findings in Jira/GitHub"	findings-to-tickets
   "Big picture across all our repos"	portfolio-aggregator → lean-deck-builder/lean-report-writer
   "Write the release notes for what we fixed"	findings-diff → lean-changelog
   "Review this contributed skill"	skill-conformance-checker
   "Our evals are slow/expensive"	ai-eval-efficiency-audit
   "Serve more tokens per GPU"	llm-serving-optimizer
   "Should we fine-tune or just prompt better?"	fine-tune-vs-prompt-advisor
   "Our Electron app drains laptops"	desktop-app-audit
   "Tune our existing Lambdas"	serverless-function-tuner
   "Our newsletter is heavy / list is dead"	email-campaign-audit
   "Teach the team from these findings"	lean-education-builder

   If a needed skill is not installed, say so plainly, do the best honest job inline, and mark the gap in out_of_scope.

3. Right-size effort per hop. The router practices what the suite preaches:

   • Classification and data extraction are cheap steps — do them tersely, no extended deliberation.
   • Reserve deep reasoning for synthesis-heavy steps (writing the report narrative, designing an architecture).
   • Never re-run an audit whose findings file already exists in the workspace for the same subject — reuse it and say you did. Cache-first is a green pattern too.
   • Cap pipelines at what the request needs. "Is my site green?" does not need a deck.

4. Run the pipeline. For each step, read that skill's SKILL.md and follow it. Persist each producer's output as <subject-slug>.lean-findings.json in the working directory so later steps (and later conversations) can reuse it.

5. Merge when multiple producers ran. Merging is mechanical:

   • Concatenate findings arrays; keep each finding's original producer traceable by prefixing id with the skill name if the same id appears in multiple files.
   • Union passed and out_of_scope.
   • Keep every methodology paragraph — consumers must present all of them.
   • Never de-duplicate across subjects (an image problem on two sites is two findings).

6. Close with a one-line receipt of what ran: skills invoked, findings counts by severity, and where the findings files live. Keep it to 1–2 sentences unless the user asked for detail.

Honesty rules (inherited by every pipeline)

These are suite-wide and non-negotiable; repeat them to downstream skills if there is any doubt:

1. Never invent numbers — but distinguish what can and cannot be counted. Wasted compute has three symptoms: energy (E), cost, and carbon. Energy and carbon impact stay directional by design — no "saves 47% energy" or CO2e grams without measurement. But cost drivers often can be counted from static analysis (tokens, GB, instance-hours, requests, file counts). When a driver is countable, name it in the finding's optional cost_signal field: {driver, observed, direction}. Never convert a counted driver into a dollar figure without the user's billing rate — the driver is the honest currency. For measured energy/carbon numbers, point users to CodeCarbon, Cloud Carbon Footprint, Kepler, or the GSF Impact Framework.
2. Surface trade-offs. Caching adds staleness; carbon-aware scheduling adds latency; edge inference shifts embodied carbon to client devices. Name them.
3. Refuse patterns that context makes wrong. Real-time systems shouldn't be batched; tiny internal tools don't need SSR.
4. Every report carries its methodology. If a consumer skill receives findings without a methodology field, ask the producer step to add one or write an honest caveat.

What this skill is not

• Not a measurement tool — it orchestrates estimates and pattern audits, not meters.
• Not a substitute for the individual skills: it should stay thin. If the router starts containing audit logic, that logic belongs in a skill.