{"id":43048364,"url":"https://github.com/hummbl-dev/hummbl-monorepo","last_synced_at":"2026-01-31T10:09:21.706Z","repository":{"id":327266422,"uuid":"1108604004","full_name":"hummbl-dev/hummbl-monorepo","owner":"hummbl-dev","description":"monorepo for all HUMMBL Systems - see more at hummbl.io","archived":false,"fork":false,"pushed_at":"2026-01-22T20:53:50.000Z","size":63209,"stargazers_count":0,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T13:11:30.449Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hummbl-dev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":"AUDIT_COMPLETION_SUMMARY.txt","citation":null,"codeowners":".github/CODEOWNERS","security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"docs/AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-02T17:07:11.000Z","updated_at":"2026-01-21T12:06:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hummbl-dev/hummbl-monorepo","commit_stats":null,"previous_names":["hummbl-dev/hummbl-monorepo"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hummbl-dev/hummbl-monorepo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-monorepo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-monorepo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-monorepo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-monorepo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hummbl-dev","download_url":"https://codeload.github.com/hummbl-dev/hummbl-monorepo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-monorepo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28937876,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-31T08:53:31.997Z","status":"ssl_error","status_checked_at":"2026-01-31T08:51:38.521Z","response_time":128,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-31T10:09:20.909Z","updated_at":"2026-01-31T10:09:21.699Z","avatar_url":"https://github.com/hummbl-dev.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HUMMBL Monorepo\n\n[![CI](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/ci.yml/badge.svg)](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/ci.yml)\n[![PR Checks](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/pr.yml/badge.svg)](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/pr.yml)\n[![CodeQL](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/codeql.yml/badge.svg)](https://github.com/hummbl-dev/hummbl-monorepo/actions/workflows/codeql.yml)\n![Audit Score](\u003chttps://img.shields.io/badge/Audit%20Score-78%2F100%20(B%2B)-brightgreen\u003e)\n\n**Sovereign Intelligence Stack** - A pnpm monorepo for HUMMBL projects and packages.\n\n## Structure\n\n```\nhummbl-monorepo/\n├── apps/\n│   ├── mcp-server/      # Model Context Protocol server with Base120 mental models\n│   ├── web/             # Vite + React web application\n│   └── workers/         # Cloudflare Workers (D1, KV, R2, Queues)\n├── packages/\n│   └── core/            # Shared core types and utilities\n├── docs/\n│   ├── bugs/            # Bug reports and incident documentation\n│   ├── examples/        # Training examples and best practices\n│   ├── protocols/       # Validation protocols and standards\n│   ├── proposals/       # Improvement proposals and RFCs\n│   └── reference/       # Reference documentation and quick guides\n├── tests/               # Test suites and reproduction scenarios\n└── .github/\n    └── workflows/       # CI/CD workflows\n```\n\n## HUMMBL Base120 Framework\n\n**6 Transformations, 120 Mental Models** for systematic problem-solving:\n\n| Code   | Transformation | Description                                               | Models |\n| ------ | -------------- | --------------------------------------------------------- | ------ |\n| **P**  | Perspective    | Frame and name what is. Anchor or shift point of view.    | 20     |\n| **IN** | Inversion      | Reverse assumptions. Examine opposites, edges, negations. | 20     |\n| **CO** | Composition    | Combine parts into coherent wholes.                       | 20     |\n| **DE** | Decomposition  | Break systems into components.                            | 20     |\n| **RE** | Recursion      | Apply operations iteratively, outputs→inputs.             | 20     |\n| **SY** | Meta-Systems   | Systems of systems, coordination, emergence.              | 20     |\n\n\u003e **⚠️ Important**: Always validate transformation references using the MCP server's `get_transformation` tool.  \n\u003e See [Transformation Validation Protocol](docs/protocols/transformation-validation.md) for details.\n\n## Getting Started\n\n### Prerequisites\n\n- **Node.js**: v18 or higher\n- **pnpm**: v9.14.4 (recommended)\n\n### Installation\n\n```bash\n# Install pnpm globally (if not already installed)\nnpm install -g pnpm@9.14.4\n\n# Install dependencies\npnpm install\n```\n\n## MCP Server Tools\n\nThe HUMMBL MCP server provides mental model access via Model Context Protocol:\n\n### Available Tools\n\n1. **`search_models`** - Search Base120 framework for mental models\n\n   ```typescript\n   search_models({ query: 'feedback', transformation: 'RE' });\n   ```\n\n2. **`get_model_details`** - Get full definition + system prompt for a model\n\n   ```typescript\n   get_model_details({ id: 'RE8' }); // Returns Bootstrapping model\n   ```\n\n3. **`get_transformation`** - Validate transformation definitions (⚠️ Use this first!)\n   ```typescript\n   get_transformation({ code: 'RE' }); // Returns: Recursion definition\n   ```\n\n### Transformation Validation\n\n**CRITICAL**: Always validate transformation references before use.\n\n```typescript\n// ❌ INCORRECT - Fabricating meaning\n'RE stands for Reconstruct...'; // WITHOUT validation\n\n// ✅ CORRECT - Validated first\nconst transform = await get_transformation({ code: 'RE' });\n// Returns: \"RE = Recursion: Apply operations iteratively, outputs→inputs\"\n```\n\nSee [Transformation Validation Protocol](docs/protocols/transformation-validation.md) for complete guidelines.\n\n## Development\n\n### Run All Apps in Dev Mode\n\n```bash\npnpm dev\n```\n\n### Run a Specific App\n\n```bash\n# MCP Server\npnpm --filter @hummbl/mcp-server dev\n\n# Web App\npnpm --filter @hummbl/web dev\n\n# Workers\npnpm --filter @hummbl/workers dev\n```\n\n### Build All Packages\n\n```bash\npnpm build\n```\n\n### Run Tests\n\n```bash\npnpm test\n```\n\n## Available Scripts\n\nAll scripts use Turbo for fast, cached builds:\n\n- `pnpm dev` - Start development mode across all apps\n- `pnpm build` - Build all packages and apps\n- `pnpm test` - Run tests across all workspaces\n- `pnpm lint` - Lint all code with ESLint\n- `pnpm type-check` - Type check all TypeScript code\n- `pnpm format` - Format code with Prettier\n- `pnpm format:check` - Check code formatting\n- `pnpm validate` - Run lint, type-check, test, and build\n- `pnpm clean` - Clean all build artifacts and node_modules\n\n## Workspace Commands\n\nWork with specific packages using pnpm filters:\n\n```bash\n# Install a dependency in a specific package\npnpm --filter @hummbl/web add react\n\n# Run a script in a specific package\npnpm --filter @hummbl/core build\n\n# Run a script in all packages\npnpm -r build\n```\n\n## Documentation\n\n### Core Documentation\n\n- **[Transformation Reference](docs/reference/transformations-reference.md)** - Quick reference for all 6 transformations\n- **[Validation Protocol](docs/protocols/transformation-validation.md)** - How to validate transformation references\n- **[Training Examples](docs/examples/transformation-validation-examples.md)** - Correct/incorrect patterns\n- **[Bug Reports](docs/bugs/)** - Incident documentation and fixes\n- **[Improvement Proposals](docs/proposals/)** - Architecture enhancements\n\n### Audit Reports\n\n- **[Audit Executive Summary](AUDIT_EXECUTIVE_SUMMARY.md)** - Quick overview of repository health (B+ grade)\n- **[Comprehensive Audit Report](COMPREHENSIVE_AUDIT_REPORT.md)** - Detailed analysis of all aspects\n- **[Action Items](ACTION_ITEMS.md)** - Prioritized remediation checklist\n- **[Day 2 Operational Readiness](DAY2_AUDIT.md)** - Production deployment readiness\n\n## Adding a New Package\n\n1. Create a new directory in `packages/`\n2. Add a `package.json`:\n\n```json\n{\n  \"name\": \"@hummbl/your-package\",\n  \"version\": \"1.0.0\",\n  \"main\": \"dist/index.js\",\n  \"types\": \"dist/index.d.ts\"\n}\n```\n\n3. The workspace will automatically detect it\n\n## Adding a New App\n\n1. Create a new directory in `apps/`\n2. Add a `package.json` with a unique name\n3. Reference shared packages:\n\n```json\n{\n  \"dependencies\": {\n    \"@hummbl/core\": \"workspace:*\"\n  }\n}\n```\n\n## Tooling\n\n- **pnpm** - Fast, disk space efficient package manager\n- **Turbo** - High-performance build system with caching\n- **TypeScript** - Type-safe JavaScript\n- **ESLint** - Code linting (ESLint v9 flat config)\n- **Prettier** - Code formatting\n- **Husky** - Git hooks for pre-commit checks\n- **lint-staged** - Format staged files before commit\n\n## CI/CD\n\nGitHub Actions workflows automatically:\n\n- ✅ Lint code\n- ✅ Type check\n- ✅ Run tests\n- ✅ Build all packages\n- 📦 Publish packages to npm with provenance\n\n## Contributing\n\n1. Clone the repository\n2. Run `pnpm install`\n3. Create a feature branch\n4. Make your changes\n5. Run `pnpm validate` to ensure all checks pass\n6. Commit and push (pre-commit hooks will auto-format)\n7. Open a pull request\n\n## License\n\nUNLICENSED\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummbl-dev%2Fhummbl-monorepo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhummbl-dev%2Fhummbl-monorepo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummbl-dev%2Fhummbl-monorepo/lists"}