loomstack

loomstack is an agent-operable fullstack framework. Humans specify product logic; coding agents work inside an explicit, generated, verifiable architecture.

Less ambiguity. Fewer wrong edits. Predictable fullstack changes.

loomstack v0.1 has one golden path: TypeScript, pnpm, React + Vite, Koa, PostgreSQL, Zod-backed schemas, and Vitest. It deliberately does not offer alternate adapters or multiple valid application structures.

Quick start

Requirements: Node 22+, pnpm 11+, and Docker Compose.

Start a new app

npm create loomstack-app@latest my-app
cd my-app
pnpm install
pnpm loomstack init

init checks the project and starts the web, API, and PostgreSQL containers. Open http://localhost:3000. Use pnpm loomstack init --no-start to set up without starting Docker.

Open the project in your preferred coding agent—for example, Claude Code:

claude
# or: codex
# or: pi

Then describe the feature you want:

Read the root AGENTS.md first. Create a new feature named weather using the
canonical LoomStack workflow, then read the feature-local AGENTS.md before
editing it. Build a weather app with a UI where users enter a location. Query
a free online weather API that requires no paid account, persist each requested
weather response in PostgreSQL, and let users view the returned weather and
previous searches. Keep API and database access out of the UI. Generate,
verify, and test the feature before finishing.

The coding agent will use LoomStack's structured context, scaffold the feature, edit only canonical authored files, regenerate wiring, and verify the result.

Work on the framework

pnpm install
pnpm loomstack --cwd examples/manager-crm verify --json
pnpm test
pnpm typecheck
pnpm build

The contract

React        = presentation
Koa          = transport
features/*   = product behavior and source of truth
generated    = wiring; never hand-edit

Every feature declares its entities, routes, actions, queries, views, permissions, and tests. loomstack generates registries and transport, exposes scoped context to agents, and rejects architecture drift with stable repairable errors.

Agent workflow

For any change, an agent follows one deterministic loop:

pnpm loomstack context feature <feature> --json
pnpm loomstack affected <authored-file> --json
# edit feature.yaml/schema/action/query/view/test files
pnpm loomstack generate --json
pnpm loomstack verify feature <feature> --json
pnpm test

Generated source begins with:

// GENERATED BY loomstack. DO NOT EDIT.

Generated JSON has "generatedBy": "loomstack" and "doNotEdit": true. Hashes in .loomstack/generated-files.json distinguish manual edits from stale output.

Canonical feature

features/<feature-id>/
  feature.yaml
  AGENTS.md
  model.schema.ts
  permissions.policy.ts
  actions/*.action.ts
  queries/*.query.ts
  ui/*.view.tsx
  ui/*.component.tsx
  ui/*.form.tsx
  tests/*.test.ts

Mutations use action(). Reads use query(). Runtime input, output, and authentication checks are centralized. React views call named generated RPC clients. Koa exposes only:

POST /_loomstack/actions/<actionName>
POST /_loomstack/queries/<queryName>

CLI

All agent-facing commands support --json.

Command	Purpose
loomstack create app <name>	Create the complete golden-path application
loomstack create feature <name>	Scaffold one canonical feature and refresh generation
loomstack generate	Regenerate routes, clients, registries, graph, context, and hashes
loomstack dev start|refresh|status|stop	Manage the Docker development stack
loomstack verify [feature <name>]	Enforce manifests, boundaries, and generated freshness
loomstack context [feature <name>]	Return scoped edit context
loomstack graph	Return the feature graph
loomstack affected <file>	Return likely related authored files
loomstack explain <code>	Return the reason and repair for a stable error
loomstack doctor	Check Node, pnpm, config, and TypeScript setup

See the architecture guide and CLI contracts for details.

Packages

• @loomstack/core — manifests, project scanning, graph, errors
• @loomstack/runtime — schemas, actions, queries, policies, execution
• @loomstack/generator — deterministic app, feature, route, registry, and context generation
• @loomstack/verifier — architecture and freshness enforcement
• @loomstack/react — views, hooks, generated RPC client primitives
• @loomstack/koa — action/query HTTP execution
• @loomstack/postgres — PostgreSQL persistence via DATABASE_URL and a deterministic in-memory test adapter
• @loomstack/cli — command surface for agents
• create-loomstack-app — npm initializer (npm create loomstack-app@latest)

Proof app

examples/manager-crm is the repository integration fixture, recreated from the published LoomStack 0.0.2 packages. It contains people, projects, and commitments vertical slices; commitments include due dates, overdue-first ordering, and a due-soon query. Framework-root commands resolve local workspace packages, while the example's standalone lockfile resolves the published npm packages.

pnpm loomstack --cwd examples/manager-crm verify --json
pnpm --filter manager-crm test
pnpm --filter '@manager-crm/*' build

Scope

v0.1 intentionally excludes SSR, production auth/migrations, REST generation, plugins, MCP, deployment adapters, alternate UI/backend stacks, and advanced relation modeling. Those do not block proving the agent-operability thesis.