Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (stania) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

npm version downloads license

Stania

Ship production software with AI agents.
Contract-first. Parallel by default. Role-aware.

Quick Start · Docs · Frontend Guide · Commands

Stania is an engineering workflow for Claude Code. It replaces vibe coding with a disciplined system: define contracts, let agents build the backend, let frontends write specs instead of code, and ship through a pipeline that catches AI mistakes before production.

npx stania

Why Stania

Without Stania	With Stania
"Build me a booking system" → fragile code, no tests, inconsistent patterns	Contract → Agent → Tested PR in minutes
Frontend blocked waiting for backend	Frontend works on mocks from day 1
Manual review of every AI-generated line	8 AI code smell detectors + mutation testing
"Where did we leave off?" between sessions	`.stania/` tracks progress, domain model, specs
Everyone needs to know everything	Role-aware: each person sees only what's relevant

Quick Start

mkdir my-app && cd my-app
npx stania

Open Claude Code:

/st-next                        → "Run /st-bootstrap to initialize"
/st-bootstrap                   → repo, CI/CD, monorepo, deploy
/st-model                       → domain model
/st-contract create-user        → API types + mocks + client
/st-agent create-user           → autonomous backend (background)

Frontend (simultaneously):

/st-next                        → "UI spec 'signup-form' ready: /st-ui signup-form"
/st-ui signup-form              → generates component from spec
/st-ui --refine signup-form     → "add hover shadow, fade-in animation"

How It Works

 YOU (Tech Lead)              FRONTEND                    AGENT (background)
 ───────────────              ────────                    ──────────────────
 /st-contract ─────────────→  writes UI spec
 /st-agent ───────────────────────────────────────────→  implements backend
                              /st-ui (generates code)
                              /st-ui --refine (styles)         │
                                   │                           │
 review PR  ←──────────────────────────────────────────── creates PR
 /st-integrate                done

Frontend and backend never block each other. The contract is the interface.

Install

npx stania            # Install in current project
npx stania@latest     # Update to latest
npx stania uninstall  # Remove

Per-project only. Doesn't pollute other projects or waste tokens globally.

Alternative: curl

curl -fsSL https://raw.githubusercontent.com/cloudpetals/stania/main/install.sh | bash

Commands

Guidance

Command	Description
`/st-next`	What should I do now? Role-aware, reads project state, suggests 1-3 actions

Team Workflow

Command	Description
`/st-bootstrap`	Project setup — GitHub repo, CI/CD, monorepo, Vercel + Cloud Run
`/st-contract`	Define API contract → generates mocks, typed client, backend ports
`/st-agent`	Launch autonomous backend implementation in background
`/st-ui`	Generate frontend component from structured spec
`/st-ui --refine`	Adjust styles/effects in natural language
`/st-integrate`	Replace mocks with real backend + run e2e
`/st-board`	GitHub Issues/PRs kanban board

Quality

Command	Description
`/st-check`	Parallel validation — typecheck + lint + tests + AI smell scan
`/st-e2e`	Generate Playwright E2E tests from contracts
`/st-migrate`	Handle contract evolution — detect breaking changes, update dependents
`/st-seed`	Generate realistic test fixtures (builder pattern)
`/st-deps`	Dependency health — security audit + auto-fix
`/st-mutate`	Mutation testing — are your tests actually catching bugs?

Pipeline

Command	Description
`/st-quick`	Fast path — validate + commit (for simple changes)
`/st-spec`	Formal spec with invariants, errors, edge cases
`/st-build`	Layer-by-layer generation — domain → app → infra
`/st-ship`	Pre-deploy audit + PR creation
`/st-retro`	Session close — decisions, docs, next steps

Utilities

Command	Description
`/st-model`	Extract DDD domain model → `.stania/domain-model.json`
`/st-status`	Progress report per bounded context

Frontend Workflow

The frontend person writes specs, not code. Claude generates everything.

1. Pick a layout from the catalog (9 options):

LIST · DETAIL · FORM · DASHBOARD · GRID · SIDEBAR · MODAL · SPLIT · EMPTY

2. Fill the spec (what it shows, what users can do, what happens on error):

# Order List

## Layout
**Layout**: LIST
**Slots**:
  - header: "Orders" + date filter
  - item-row: guest name, date, party size, status badge
  - pagination: infinite scroll

## States
| loading | 5 skeleton rows |
| empty   | "No orders yet" + create CTA |
| error   | "Failed to load" + retry |

## Interactions
| click row    | navigate to /orders/:id |
| change filter | refetch with new params |

3. Generate: /st-ui order-list

4. Adjust: /st-ui --refine order-list → "more shadow on hover, fade-in animation"

Full guide: docs/frontend-guide.md

Architecture

project/
├── apps/
│   ├── web/                  ← Next.js 15 (Vercel)
│   └── api/                  ← Backend (Cloud Run)
├── packages/
│   └── contracts/            ← Source of truth
│       └── generated/        ← mocks + client + ports (auto-generated)
└── .stania/                  ← State tracking + UI specs

Frontend standards (enforced automatically)

Server Components by default — "use client" only for interactivity
Feature-based folders — component + hook + test colocated
TanStack Query for data fetching
React Hook Form + Zod for forms
shadcn/ui + Tailwind CSS (mobile-first)
axe-core accessibility in every test
4 states mandatory: loading, empty, error, success
Lighthouse CI: Performance ≥90, Accessibility ≥95

Backend standards (Clean Architecture + DDD)

Domain: zero external imports, private constructors, Result pattern
Value Objects over primitives (Email not string, Money not number)
Ports in domain, implementations in infrastructure
One aggregate per transaction boundary

Quality Gates

Development          CI (every PR)              On demand
───────────          ─────────────              ─────────
/st-check            GitHub Actions             /st-mutate
├─ TypeScript        ├─ typecheck + lint        └─ mutation testing
├─ Biome             ├─ tests                      (>80% kill rate)
├─ Vitest + axe      ├─ Lighthouse CI
└─ AI smell scan     └─ bundle budget (<100KB)

AI Code Smells

Stania detects 8 patterns that AI commonly produces:

#	Smell	What it catches
1	API Hallucination	Methods that don't exist in the library
2	Happy Path Bias	Missing error handling
3	Invisible Coupling	Domain importing from infrastructure
4	Security Blindness	Unsanitized input, PII in logs
5	Over-engineering	Abstractions for non-existent requirements
6	Test Theater	Tests that verify nothing meaningful
7	Context Amnesia	Same problem solved differently across files
8	Stale Patterns	Using deprecated approaches

Role System

Stania adapts to who you are:

Role	Sees	Focus
lead	All commands	Contracts, architecture, PR reviews
frontend	/st-ui, /st-next, /st-ui --refine	Specs and visual adjustments
pm	/st-board, /st-next, /st-status	Progress and blockers

Set on first run: /st-next → "What's your role?" → saved to .stania/me.json

Token Efficiency

Strategy	Impact
Per-project install	~52K tokens saved per turn in other projects
Output truncation	~80% less context from tool output
Parallel validation	3 simultaneous calls instead of sequential
Incremental validation	Skip if unchanged since last check
Role filtering	Smaller skill surface per user type

Stack Support

Stania detects and adapts:

	TypeScript	Python	Go
Typecheck	tsc strict	mypy	go vet
Lint	Biome	ruff	golangci-lint
Test	Vitest	pytest	go test
Mutate	Stryker	mutmut	go-mutesting

Requirements

Claude Code (Max plan recommended for background agents)
Node.js ≥ 18
Git + GitHub CLI (gh)

Documentation

Workflow Reference — Complete team + solo workflow details
Frontend Guide — Step-by-step for frontend engineers
Layout Catalog — All 9 pre-defined layouts
UI Standards — Architecture rules enforced on generation

Contributing

git clone https://github.com/cloudpetals/stania.git
cd stania
# Edit commands in commands/, skill in skills/st/SKILL.md
# Test: cd <any-project> && bash /path/to/stania/install.sh

License

MIT

Built by Cloudpetals