Skip to content
nanohypenanohype

nanohype

The factory's vocabulary

Templates, composites, standards, the SDK and the MCP server. What every other repo is described in terms of.

github.com/nanohype/nanohype ·AGENTS.md

What follows is that repo's AGENTS.md — the entry point an agent reads before working on it. It is rendered from the repo itself at build time rather than copied, so it says what the repo says today. Links in it point back at the repo they were written for.

nanohype — agent entry point

You’re an AI client (or the author of one). This file gets you running in five minutes. For the full picture of how this repo fits into a larger nanohype-stack delivery, read docs/platform-reference.md.

What this repo gives you

  • Templates (templates/<name>/) — 94 scaffolds for AI systems, applications, infrastructure, modules, and non-engineering deliverables.
  • Composites (composites/*.yaml) — 25 pre-baked multi-template stacks for common engagements (ai-chatbot, agent-team, enterprise-ai, etc.).
  • Catalog (catalog.json) — single machine-readable index of all templates + composites. Stable URL at https://raw.githubusercontent.com/nanohype/nanohype/main/catalog.json.
  • Standards (standards/) — the production bar every nanohype-stack build meets. One JSON file per guardrail, plus a human-readable README.
  • SDK (@nanohype/sdk) — TypeScript reference implementation of the rendering algorithm. One runtime dependency (a YAML parser). Works against local paths or the GitHub API.
  • MCP server (@nanohype/mcp) — exposes everything above as MCP resources and tools, mountable in Claude Desktop / Claude API / Bedrock agents.

Quickstart (60 seconds)

Fetch the catalog and pick a template:

Terminal window
curl https://raw.githubusercontent.com/nanohype/nanohype/main/catalog.json \
  | jq '.templates[] | select(.category == "ai-systems") | .name'

Render programmatically (TypeScript):

import { GitHubSource, renderTemplate } from "@nanohype/sdk";


const source = new GitHubSource({ repo: "nanohype/nanohype" });
const { manifest, files } = await source.fetchTemplate("rag-pipeline");
const result = renderTemplate(manifest, files, {
  ProjectName: "my-rag-bot",
  LlmProvider: "anthropic",
});
// result.files — write these to disk yourself; hooks are returned, not executed

Or via MCP (Claude Desktop snippet):

{
  "mcpServers": {
    "nanohype": {
      "command": "npx",
      "args": ["-y", "@nanohype/mcp"],
    },
  },
}

Then ask the model: “List templates in the ai-systems category” — the MCP tool surfaces the catalog directly.

Contract surface

If you’re writing a client (not just consuming):

Add a new template

  1. Create templates/<name>/ with template.yaml, skeleton/, README.md.
  2. Follow field order: apiVersion, kind, name, displayName, description, version, license, persona, category, tags, variables, conditionals, hooks, composition, prerequisites.
  3. Placeholders are __SCREAMING_SNAKE__ and appear both in file content and filenames. Variables that drive conditionals are bool.
  4. Run ./scripts/validate.sh templates/<name> — full validation including schema, hook naming, prereqs.
  5. Run npm run generate:catalog to re-emit catalog.json. CI verifies no drift.
  6. Open a PR. CI runs validate:schema (via validate:catalog), validate:catalog, validate:standards, verify:catalog, and verify:library.

Add a new composite

  1. Create composites/<name>.yaml. Use kind: composite, apiVersion: nanohype/v1.
  2. Reference templates by name; declare entry conditions and variable overrides.
  3. Validate against schemas/composite.schema.json (npm run validate:composites). Composites have their own schema; a composite does not satisfy the template schema.
  4. Re-generate the catalog (npm run generate:catalog).

Add a new standard

Only do this if you’re publishing a new dimension of the production bar that external clients should obey. The existing standards cover the canonical guardrails — language toolchain, version currency, platform-tenant contract, LLM policy, quality-rubric dimensions, testing rubric, resource tagging, resource naming, observability SLOs, telemetry pipeline, SEO baseline. Adding another:

  1. Add the new kind enum value to schemas/standards.schema.json and a per-kind content schema branch.
  2. Write standards/<new-name>.json conforming to your new branch.
  3. Update standards/README.md with the human-readable form.
  4. Bump the SDK’s loadStandards() return type to include the new field.
  5. CI runs validate:standards — no extra wiring needed.

Conventions

  • 2-space indent for YAML, JSON, TypeScript, Markdown. 4-space for Python. Tabs for Go and Makefiles.
  • Templates use license: Apache-2.0. Hook name is always install-dependencies.
  • All templates include nestsInside: [monorepo] in composition (exception: the monorepo template itself).
  • Module templates carry a runtime suffix (-ts, -go, -py) or a framework name (module-spring-security). Unsuffixed names mean the module is language-agnostic.
  • Skeleton code uses latest stable library versions and idiomatic patterns per language. No LangChain.

Pointers