{"_id":"@anarchitecture/madrigal","name":"@anarchitecture/madrigal","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@anarchitecture/madrigal","version":"0.1.0","description":"A config-driven, pluggable knowledge compiler inspired by Style Dictionary","license":"Apache-2.0","author":{"name":"Block, Inc."},"repository":{"type":"git","url":"git+https://github.com/block/madrigal.git"},"homepage":"https://github.com/block/madrigal#readme","bugs":{"url":"https://github.com/block/madrigal/issues"},"keywords":["knowledge-compiler","knowledge-base","ai-agents","style-dictionary","rules","cli"],"type":"module","packageManager":"pnpm@10.12.4","main":"dist/index.js","types":"dist/index.d.ts","bin":{"madrigal":"dist/cli.js"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"publishConfig":{"access":"public","provenance":true},"scripts":{"build":"tsc -p tsconfig.build.json && cd src/dev/ui && npm run build","dev":"tsc -p tsconfig.build.json --watch --preserveWatchOutput & cd src/dev/ui && npm run dev","dev:server":"node --watch-path=dist dist/cli.js dev","typecheck":"tsc --noEmit","lint":"biome lint .","check":"biome check .","format":"biome format --write .","test":"vitest run","clean":"rm -rf dist","changeset":"changeset","version-packages":"changeset version","release":"pnpm build && changeset publish","prepublishOnly":"pnpm build","prepare":"lefthook install"},"engines":{"node":">=18"},"peerDependencies":{"@anthropic-ai/sdk":">=0.27.0","@modelcontextprotocol/sdk":">=1.0.0","zod":">=3.0.0"},"peerDependenciesMeta":{"@anthropic-ai/sdk":{"optional":true},"@modelcontextprotocol/sdk":{"optional":true},"zod":{"optional":true}},"dependencies":{"@hono/node-server":"^1.13.0","fast-glob":"^3.3.2","gray-matter":"^4.0.3","hono":"^4.6.0","yaml":"^2.3.4"},"devDependencies":{"@anthropic-ai/sdk":"^0.90.0","@biomejs/biome":"^2.4.10","@changesets/changelog-github":"^0.6.0","@changesets/cli":"^2.31.0","@modelcontextprotocol/sdk":"^1.28.0","@types/node":"^20.11.0","lefthook":"^2.1.4","typescript":"^5.3.3","vitest":"^1.2.0","zod":"^4.3.6"},"_id":"@anarchitecture/madrigal@0.1.0","gitHead":"944709a193b33ed706668ff6ea65f90fd91f818e","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-pznE6HaKkyWnydy2JoqoTbB6u6luCI2z7TV9l+TrlKnSS3pa5msDZ0b6XuzPBX8yW+nziH7aVfsGDrjh5kCOvw==","shasum":"a4092b94845ad4338b6529172fda7db8cc52d8b9","tarball":"https://registry.npmjs.org/@anarchitecture/madrigal/-/madrigal-0.1.0.tgz","fileCount":190,"unpackedSize":2173743,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@anarchitecture%2fmadrigal@0.1.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH5b6y3Kj4S+2niEWvPKkA6+uFvFZ819kRM+dr/jeiUnAiEA205j1BENnVv4V43vBqQ6vEIPtkjM4tD8iRcB4J56fGg="}]},"_npmUser":{"name":"nahiyankhan","email":"nahiyan.khan@gmail.com"},"directories":{},"maintainers":[{"name":"nahiyankhan","email":"nahiyan.khan@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/madrigal_0.1.0_1780548065864_0.8253130275778178"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-04T04:41:05.628Z","0.1.0":"2026-06-04T04:41:06.068Z","modified":"2026-06-04T04:41:06.548Z"},"maintainers":[{"name":"nahiyankhan","email":"nahiyan.khan@gmail.com"}],"description":"A config-driven, pluggable knowledge compiler inspired by Style Dictionary","homepage":"https://github.com/block/madrigal#readme","keywords":["knowledge-compiler","knowledge-base","ai-agents","style-dictionary","rules","cli"],"repository":{"type":"git","url":"git+https://github.com/block/madrigal.git"},"author":{"name":"Block, Inc."},"bugs":{"url":"https://github.com/block/madrigal/issues"},"license":"Apache-2.0","readme":"# Madrigal\n\nA config-driven, pluggable knowledge compiler. Madrigal transforms structured knowledge (markdown files with frontmatter) into multiple output formats — JSON bundles, AI skill files, rule sets, and more.\n\nInspired by [Style Dictionary](https://amzn.github.io/style-dictionary/), Madrigal applies the same \"define once, compile everywhere\" philosophy to design knowledge, coding guidelines, and organizational rules.\n\n## Quick Start\n\n```bash\nnpm install @anarchitecture/madrigal\n```\n\nCreate a `madrigal.config.yaml`:\n\n```yaml\nsources:\n  - \"knowledge/**/*.md\"\n\ndomains:\n  accessibility:\n    description: \"Accessibility guidelines\"\n\nbrands:\n  acme:\n    include:\n      - global\n\nplatforms:\n  skill-file:\n    format: skill-md\n  json-export:\n    format: json-bundle\n```\n\nCreate a knowledge file at `knowledge/contrast.md`:\n\n```markdown\n---\ntitle: Color Contrast Requirements\ndomain: accessibility\nseverity: error\ntags:\n  - a11y\n  - wcag\n---\n\nAll text must meet WCAG 2.1 AA contrast requirements:\n- Normal text: minimum 4.5:1 contrast ratio\n- Large text: minimum 3:1 contrast ratio\n```\n\nBuild programmatically:\n\n```typescript\nimport { build } from '@anarchitecture/madrigal';\n\nconst result = await build();\n\nfor (const output of result.results) {\n  console.log(`${output.platform}: ${output.unitCount} units`);\n  console.log(output.output);\n}\n```\n\n## Concepts\n\n### Knowledge Units\n\nThe atomic unit. Each `.md` file with frontmatter becomes a `KnowledgeUnit` with an id, title, body, domain, severity, tags, and provenance tracking.\n\n### Domains\n\nLogical groupings of knowledge (e.g., `accessibility`, `typography`, `layout`). Defined in config and validated at load time.\n\n### Brands\n\nOrganizational units that can inherit from each other. A brand can `include` other brands/groups, and brand-specific knowledge overrides globals with the same id.\n\n### Severity\n\nFive levels: `error` > `warning` > `info` > `context` > `deprecated`. Severity controls enforcement behavior and output filtering.\n\n### Formats\n\nOutput compilers that transform knowledge units into specific formats. Four built-in formats are included:\n\n| Format | Description |\n|--------|-------------|\n| `json-bundle` | Searchable JSON with metadata |\n| `skill-md` | Markdown skill file for AI agents |\n| `ai-rules-md` | Rule file for AI coding assistants |\n| `mesh-domain` | AI app-info mesh domain format |\n\n### Platforms\n\nNamed build targets in config. Each platform specifies a format and optional grouping (`brand`, `domain`, or `system`).\n\n## Configuration Reference\n\n```yaml\n# Glob patterns for knowledge source files\nsources:\n  - \"knowledge/**/*.md\"\n\n# Domain definitions\ndomains:\n  <name>:\n    description: \"...\"\n\n# Brand definitions\nbrands:\n  <name>:\n    systems:        # Optional: associated design systems\n      - web\n    include:        # Optional: inherit from other brands\n      - global\n\n# Build targets\nplatforms:\n  <name>:\n    format: json-bundle    # Required: registered format name\n    groupBy: brand         # Optional: brand | domain | system\n    destination: out/      # Optional: output path\n```\n\n## Knowledge File Format\n\n```markdown\n---\ntitle: Rule Title            # Required (or id)\nid: custom-id                # Optional, generated from filename if omitted\ndomain: accessibility        # Optional, defaults to 'default'\nseverity: error              # Optional: error|warning|info|context|deprecated\nbrand: acme                  # Optional, omit for global rules\nsystem: web                  # Optional\ntags:                        # Optional\n  - a11y\n  - wcag\n---\n\nMarkdown body content here.\n```\n\n## Plugin System\n\n### Custom Formats\n\n```typescript\nimport { defaultRegistry, type Format } from '@anarchitecture/madrigal';\n\nconst myFormat: Format = {\n  name: 'custom-html',\n  extension: '.html',\n  compile(units, options) {\n    return `<html>...</html>`;\n  },\n};\n\ndefaultRegistry.register(myFormat);\n```\n\n### Custom Preprocessors\n\nPreprocessors transform knowledge units after loading but before compilation:\n\n```typescript\nimport { defaultPreprocessorRegistry, type Preprocessor } from '@anarchitecture/madrigal';\n\nconst enricher: Preprocessor = {\n  name: 'tag-enricher',\n  async process(units, config) {\n    return units.map(u => ({\n      ...u,\n      tags: [...u.tags, 'enriched'],\n    }));\n  },\n};\n\ndefaultPreprocessorRegistry.register(enricher);\n```\n\n### Adapter Interfaces\n\nMadrigal exports `StorageAdapter` and `SearchAdapter` interfaces for implementing custom backends (databases, vector stores, etc.).\n\n## API\n\n### `build(options?)`\n\nRun the full pipeline: load config, load knowledge, run preprocessors, compile all platforms.\n\n### `loadConfig(path?)`\n\nLoad and parse a `madrigal.config.yaml` file.\n\n### `loadKnowledge(options)`\n\nLoad knowledge units from markdown files matching source globs.\n\n### `resolveForBrand(options)`\n\nResolve knowledge units for a specific brand, applying inheritance and severity overrides.\n\n### `validateConfig(config, formatNames?)`\n\nValidate a configuration object.\n\n### `serveMcp(options?)`\n\nStart a stdio MCP server that exposes five tools for querying the knowledge base:\n`search_knowledge`, `get_knowledge_unit`, `list_knowledge_units`, `get_brand_rules`, `review_content`.\n\n```typescript\nimport { serveMcp } from '@anarchitecture/madrigal';\nimport { dirname, resolve } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\nconst baseDir = dirname(fileURLToPath(import.meta.url));\n\n// Single bundle\nawait serveMcp({ baseDir, bundlePath: 'publish/to-artifactory/knowledge.json' });\n\n// Multiple bundles merged into one index (for aggregator repos)\nawait serveMcp({\n  baseDir,\n  bundlePath: 'publish/to-artifactory/knowledge.json',\n  bundlePaths: [\n    resolve(baseDir, '../other-repo/publish/to-artifactory/knowledge.json'),\n  ],\n});\n```\n\nSave this as `mcp-server.js` at the repo root and register it in your MCP client config.\n\n## Skills Convention\n\nRepos that use Madrigal should own their agent skills alongside their knowledge. Skills live in `skills/{skill-name}/SKILL.md` — always a named subdirectory, never at the repo root. This mirrors the local install path (`~/.claude/skills/{name}/SKILL.md`) so publishing is mechanical.\n\n**Single-skill repo:**\n```\nskills/\n  my-knowledge-base/\n    SKILL.md\n```\n\n**Multi-skill repo** (e.g. one skill per brand or design system):\n```\nskills/\n  arcade/\n    SKILL.md\n  market/\n    SKILL.md\n```\n\nSkill files reference the MCP tools (`search_knowledge`, etc.) with domain-specific routing instructions. The repo team owns the skill — it is not generated by Madrigal.\n\nTo install a skill locally for development:\n```bash\nmkdir -p ~/.claude/skills/{skill-name}/\nln -sf \"$(pwd)/skills/{skill-name}/SKILL.md\" ~/.claude/skills/{skill-name}/SKILL.md\n```\n\n## Release Workflow\n\nMadrigal uses [Changesets](https://github.com/changesets/changesets) for\nversioning and npm publishing.\n\nFor a release-bearing change, run:\n\n```bash\npnpm changeset\n```\n\nAfter the change lands on `main`, the `Release` GitHub Actions workflow creates\na version PR when changesets are pending. When that version PR lands, the same\nworkflow builds Madrigal and publishes it to npm with provenance. The workflow\nexpects the npm automation token in `MADRIGAL_NPM_PUBLISH_TOKEN`.\n\nManual release commands are also available:\n\n```bash\npnpm version-packages\npnpm release\n```\n\n## Project Resources\n\n| Resource | Description |\n|----------|-------------|\n| [CODEOWNERS](./CODEOWNERS) | Project lead(s) |\n| [GOVERNANCE.md](./GOVERNANCE.md) | Project governance |\n| [LICENSE](./LICENSE) | Apache License, Version 2.0 |\n","readmeFilename":"README.md","_rev":"1-deb1cdd392972748b887c4374f4e45be"}