@flowstack-ui/agent-tools 0.1.0-bootstrap.0

package/.codex-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "flowstack-ui",
+  "version": "0.1.0-bootstrap.0",
+  "description": "Exact-version workflows for building, composing, reviewing, and maintaining FLOWSTACK UI.",
+  "author": {
+    "name": "FLOWSTACK UI",
+    "url": "https://github.com/flowstack-ui"
+  },
+  "homepage": "https://agents.brick-ui.com",
+  "repository": "https://github.com/flowstack-ui/agent-tools",
+  "license": "MIT",
+  "keywords": [
+    "flowstack",
+    "brick-ui",
+    "atom-ui",
+    "design-system",
+    "skills"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "FLOWSTACK UI",
+    "shortDescription": "Build with exact FLOWSTACK package guidance",
+    "longDescription": "Build, compose, review, and maintain FLOWSTACK interfaces with exact-version public package Agent Knowledge.",
+    "developerName": "FLOWSTACK UI",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Skills"
+    ],
+    "websiteURL": "https://agents.brick-ui.com",
+    "defaultPrompt": [
+      "Build this interface with exact FLOWSTACK guidance.",
+      "Review this FLOWSTACK implementation.",
+      "Plan this FLOWSTACK package change."
+    ],
+    "brandColor": "#6D4AFF"
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## 0.1.0
+
+### Added
+
+- Replace heuristic task matching with explicit Brick-first and labelled Atom
+  headless routes, omit the unqualified concatenated full corpus, harden public
+  boundary and archive-entry checks, make four-source replacement transactional,
+  and traverse every installed indexed route by digest.
+- Add the independently packable `@flowstack-ui/mcp` local stdio package with
+  eleven exact-version tools, generated capability documentation, and clean
+  JSON-RPC archive-consumer verification.
+- Incubate deterministic archive-led LLM discovery for public Atom, Brick,
+  Colors, and Theme archives with exact version provenance and bounded narrow
+  routes.
+- Add independently packaged FLOWSTACK builder, reviewer, composition, and
+  maintainer skills that resolve exact-version canonical Agent Knowledge.
+- Pin locked skill resolution by archive digest and define two-pass creation
+  for new public owners while keeping private product evidence outside the
+  future-public package.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) FLOWSTACK UI contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @flowstack-ui/agent-tools
+
+Deterministic delivery for versioned FLOWSTACK Agent Knowledge. The public
+package generates small LLM discovery, versioned package slices,
+narrow owner routes, and task slices from exact locked public package archives.
+
+The same checked corpus is available from
+[`agents.brick-ui.com`](https://agents.brick-ui.com), the npm package, the
+FLOWSTACK skills, and the read-only MCP server. Paid Blocks source, private
+Blueprints, customer data, commercial records, and authentication responses
+are outside this repository and every generated delivery surface.
+
+## Source workflow
+
+Prepare the four exact public package archives, then ingest them together:
+
+```bash
+npm run sources:ingest -- \
+  --atom /path/to/atom.tgz \
+  --brick /path/to/brick.tgz \
+  --colors /path/to/colors.tgz \
+  --theme /path/to/theme.tgz
+```
+
+Ingestion verifies archive identity, Agent Knowledge manifest and coverage
+closure, regular-file/directory archive entries, safe public paths, and source
+digests. It stages all four filtered snapshots beside the current lock and
+swaps them with rollback only after the complete replacement validates.
+Ordinary builds read only that lock and snapshot; they never inspect sibling
+repositories.
+
+```bash
+npm ci
+npm ci --prefix packages/mcp
+npm run build
+npm run check:repository
+```
+
+The root and MCP adapter are independently packable packages with separate
+lockfiles. A clean checkout must install both lockfiles before running the
+combined repository gate.
+
+The generated `public/llms.txt` is the bounded entry point. `public/index.json`
+records exact packages, versions, archive digests, output sizes, and every
+narrow route. Task slices use explicit curated owners: Brick is the default for
+finished interfaces and Atom is a separately labelled explicit headless branch.
+
+`llms-full.txt` is intentionally not emitted. A byte-bounded concatenation did
+not demonstrate useful retrieval or fit practical model contexts. Reintroducing
+one requires a curated corpus plus checked gates: at most 100,000 tokens under
+a pinned tokenizer, at most 5% duplicate normalized paragraphs, at least 90%
+top-five route recall on the checked task benchmark, 100% ownership correctness
+on the boundary regression set, and no lower answer accuracy than narrow-route
+retrieval. Raising a byte budget is not qualification.
+
+## Install
+
+Use the LLM entry point directly:
+
+```text
+https://agents.brick-ui.com/llms.txt
+```
+
+Install one workflow skill from GitHub:
+
+```bash
+npx skills add https://github.com/flowstack-ui/agent-tools/tree/main/skills/flowstack-ui-builder
+```
+
+Or configure the exact local stdio MCP release in a project's
+`.codex/config.toml`:
+
+```toml
+[mcp_servers.flowstack]
+command = "npx"
+args = ["--yes", "@flowstack-ui/mcp@0.1.0", "--project-root", "."]
+cwd = "."
+required = true
+```
+
+The hosted, read-only Streamable HTTP endpoint is
+`https://agents.brick-ui.com/mcp`. Project configuration should prefer the
+exact npm version so guidance resolves against the packages actually installed
+in that project.
+
+## MCP package
+
+`packages/mcp/` is the independently packable `@flowstack-ui/mcp` local stdio
+server. It consumes exact project-installed packages or this repository's
+explicit source lock; it does not read sibling repositories or modify the LLM
+corpus generator. The root `check:repository` gate includes its generated tool
+inventory, official JSON-RPC client tests, and exact archive consumer smoke.
+
+## Workflow skills
+
+The package also ships four independently discoverable skills under `skills/`:
+
+- `flowstack-ui-builder` implements against exact installed or locked guidance;
+- `flowstack-ui-review` audits public ownership and implementation contracts;
+- `flowstack-ui-compose` maps a supplied plan through finished Brick owners; and
+- `flowstack-ui-maintainer` coordinates package authority, stacked integration,
+  exact-version qualification, and release readiness.
+
+Each skill resolves the project's exact package version before loading package-
+owned Agent Knowledge. Locked or staged archive workflows may additionally pin
+the archive SHA-256 so one mutable candidate version cannot select different
+guidance. New owners use baseline and candidate resolution passes. An
+unavailable identity is reported instead of being silently replaced with
+current guidance. Reference captures and private research remain outside public
+package and installed files. The canonical skill directories support
+standalone GitHub installation and are also exposed by the skills-only
+FLOWSTACK plugin. The plugin is opt-in and does not silently install or
+configure MCP.
+
+## Release boundary
+
+Both npm packages are released from the same protected `v<version>` tag. CI
+must verify the checked generated corpus, both independent lockfiles, both
+packed archives, the four skill contracts, plugin metadata, and clean isolated
+consumers before trusted publishing. Published archives use npm provenance;
+hosted verification then proves that production route bytes and digests match
+the tagged source.
+
+See [the architecture contract](docs/architecture.md),
+[contribution guide](CONTRIBUTING.md), and [security policy](SECURITY.md).

package/docs/architecture.md

@@ -0,0 +1,77 @@
+# Agent Tools Delivery Architecture
+
+Agent Tools is a derived public delivery layer. It does not own package
+guidance. Atom, Brick, Colors, and Theme remain authoritative for their own
+Agent Knowledge.
+
+## Inputs
+
+`sources/lock.json` identifies exactly four public npm archives by package name,
+version, byte size, and SHA-256. Each filtered snapshot file also has an exact
+byte size and digest. Ingestion accepts Atom, Brick, Colors, and Theme together, rejects
+links and non-regular archive entries, validates the published manifest and
+zero-failure coverage identity, and copies only public package metadata,
+`dist/agents`, README/changelog/license, and public docs. A fully validated
+sibling staging tree replaces the current source set through rename with
+rollback; the current set is never deleted before the replacement is ready.
+Builds never inspect another repository.
+
+## Outputs
+
+`public/index.json` uses `flowstack.agent-delivery-index.v1`. It records source
+provenance, profile, coverage totals, owner counts, budgets, corpus decisions,
+and every generated route with size and digest.
+
+`public/llms.txt` is a small package/task index. Package slices are versioned at
+`/packages/<package>/<version>/index.txt`. Narrow routes live below `guides`,
+`components`, `operations`, and `docs`. Task slices link to those
+exact routes instead of duplicating their rules. Finished-interface task
+sections load Brick layer-selection and interface-composition first. A separate
+explicit-headless section loads Atom layer-selection and behavior-composition;
+route membership is exact and curated rather than inferred from substrings.
+
+The package does not generate `public/llms-full.txt`. The former complete
+concatenation repeated indexes, prose, and machine records without proving that
+the artifact improved retrieval. A future curated full corpus must stay at or
+below 100,000 tokens under a pinned tokenizer, contain at most 5% duplicate
+normalized paragraphs, achieve at least 90% top-five route recall, preserve
+100% ownership correctness on the boundary regression set, and perform no
+worse than narrow-route retrieval on the checked answer benchmark. It remains
+absent unless all gates are implemented and pass.
+
+## Determinism and validation
+
+Generated files contain no timestamps. The verifier rejects a changed lock or
+snapshot digest, mismatched package version, uncovered input, missing or extra
+route, stale byte, broken generated link, unresolved manifest destination,
+private or machine path, or exceeded entrypoint/task/package budget. Package
+verification packs the public package, installs that exact archive in an
+isolated temporary consumer, and traverses every indexed route by byte count
+and SHA-256.
+
+## Delivery surfaces
+
+The canonical static host is `https://agents.brick-ui.com`. It serves the same
+checked `public/` bytes as the npm package with public CORS, bounded CDN caching,
+and restrictive browser security headers. The small `/llms.txt` entry point
+links to exact-version routes; a monolithic `llms-full.txt` remains deliberately
+absent until its retrieval-quality gates pass.
+
+`@flowstack-ui/mcp` provides the local stdio transport. Consumer projects pin
+an exact package version and let the server resolve exact public FLOWSTACK
+dependencies from that project. The hosted `/mcp` endpoint uses the same tool
+definitions and server core but a locked-only repository policy; it cannot
+inspect runtime-installed dependencies or substitute a private source.
+
+Four canonical skill directories can be installed independently from GitHub
+or loaded together through the opt-in skills-only FLOWSTACK plugin. MCP remains
+separately configured so installing a skill never silently starts a process or
+changes a project.
+
+## Public boundary
+
+Only exact public archives for Atom, Brick, Colors, and Theme may enter the
+source lock. Paid Blocks source or metadata, private Blueprints, research
+memory, commercial records, authentication responses, customer application
+source, secrets, and machine-specific paths are rejected from generated,
+packed, hosted, skill, plugin, and MCP outputs.

package/docs/releasing.md

@@ -0,0 +1,26 @@
+# Releasing
+
+Agent Tools uses lockstep versions for `@flowstack-ui/agent-tools` and
+`@flowstack-ui/mcp`. A release tag is exactly `v<version>` and must point to a
+commit contained in protected `main`.
+
+1. Refresh all four public source archives together when package guidance has
+   changed, then update the changelogs and both package versions.
+2. Run `npm run check:release` from a clean checkout with both lockfiles
+   installed.
+3. Merge the green pull request. Create the exact `v<version>` tag from that
+   `main` commit and push it.
+4. The protected release environment rebuilds and verifies both archives once,
+   then publishes those exact `.tgz` files using npm trusted publishing and
+   provenance. Each package is checked first so an interrupted two-package
+   release can safely resume without republishing an existing version.
+5. Verify both registry records and provenance before creating the GitHub
+   release or promoting the matching Vercel production deployment.
+6. Run static and MCP hosted verification against
+   `https://agents.brick-ui.com` and retain the deployment commit plus index
+   digest as release evidence.
+
+Trusted publishers must be configured separately on npm for both packages,
+restricted to this repository and the release workflow. Do not use a local npm
+token, a mutable dependency range, an unverified archive, or a tag that is not
+contained in `main`.

package/docs/testing.md

@@ -0,0 +1,32 @@
+# Testing
+
+Use Node 22 or newer and install both independent lockfiles:
+
+```bash
+npm ci
+npm ci --prefix packages/mcp
+```
+
+During development, use the smallest relevant command:
+
+```bash
+npm run check:generated
+npm test
+npm run mcp:test
+npm run pack:check
+npm run mcp:pack:check
+```
+
+Before opening a pull request, run the complete repository gate:
+
+```bash
+git diff --check
+npm run check:repository
+git diff --exit-code
+```
+
+The complete gate checks deterministic generation, the public/privacy
+boundary, archive ingestion, all four skill contracts, plugin metadata, MCP
+protocol behavior, and both exact npm archives in isolated consumers. Hosted
+verification is separate because it compares a deployed production surface
+with the already-verified local corpus.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@flowstack-ui/agent-tools",
+  "version": "0.1.0-bootstrap.0",
+  "description": "Version-aware delivery adapters for public FLOWSTACK Agent Knowledge.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/flowstack-ui/agent-tools.git"
+  },
+  "bugs": {
+    "url": "https://github.com/flowstack-ui/agent-tools/issues"
+  },
+  "homepage": "https://agents.brick-ui.com",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    ".codex-plugin",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "docs",
+    "public",
+    "skills"
+  ],
+  "exports": {
+    "./llms.txt": "./public/llms.txt",
+    "./index.json": "./public/index.json",
+    "./public/*": "./public/*",
+    "./skills/*": "./skills/*",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "sources:ingest": "node scripts/ingest-archives.mjs",
+    "build": "node scripts/build-llms.mjs",
+    "build:hosting": "npm run check:generated && npm run --prefix packages/mcp check:generated",
+    "check:generated": "node scripts/build-llms.mjs --check",
+    "test": "npm run check:generated && node --test test/*.test.mjs",
+    "pack:check": "npm run build && node scripts/verify-package.mjs",
+    "mcp:build": "npm run build --prefix packages/mcp",
+    "mcp:test": "npm test --prefix packages/mcp",
+    "mcp:pack:check": "npm run pack:check --prefix packages/mcp",
+    "mcp:check": "npm run check:repository --prefix packages/mcp",
+    "host:verify": "node scripts/verify-hosted.mjs",
+    "verify:repository-contract": "node scripts/verify-repository-contract.mjs",
+    "check:focused": "npm run test",
+    "check:repository": "npm run verify:repository-contract && npm run test && npm run pack:check && npm run mcp:check",
+    "check:release": "npm run check:repository",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/client": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "@modelcontextprotocol/server": "2.0.0",
+    "zod": "4.2.1"
+  }
+}