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>/) — one scaffold per directory, for AI systems, applications, infrastructure, modules, and non-engineering deliverables. catalog.json enumerates them.
  • Composites (composites/*.yaml) — one pre-baked multi-template stack per manifest, for common engagements (ai-chatbot, agent-team, enterprise-ai, etc.). catalog.json enumerates them.
  • 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: "gateway",
});
// 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 published set is the kind enum in schemas/standards.schema.json. Adding another:

  1. Add the new kind enum value to schemas/standards.schema.json and a per-kind content schema branch. Rule arrays reference #/$defs/rule, so every rule carries a severity.
  2. Write standards/<new-name>.json conforming to your new branch, with applies_to (the deliverables it governs, including any stack scoping) and grades (dimension ids from standards/quality-rubric-dimensions.json).
  3. Update standards/README.md with the human-readable form and add a row to the Standards table in docs/platform-reference.md.
  4. In the SDK, add the name to ALL_STANDARDS and EXPECTED_KIND in sdk/src/standards.ts and to the loadStandards() bundle there; add its type to StandardName, Standard and Standards in sdk/src/types.ts, and export that type from sdk/src/index.ts.
  5. Run npm run validate:standards. It validates every file against the schema and runs scripts/check-standards-applicability.mjs, which fails on a missing applies_to or grades, an unknown dimension, or a standard the README or the Platform Reference does not name.

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