✨ Features

Stack allows creating an NPM project in a quick, easy and opinionated way with:

• A unified monorepo-driven and git-driven approach for all kinds of projects (single-purpose library, multiple libraries, application(s), ...)
• Support for several application templates (for now, only a default template is available, but others can be added later).
• Standardized file structure including optional folder creation such as examples, packages, ...
• Enable all project lifecycle steps with commands from the setup, check, fix, build, and test to the versioning and release.
• Built-in configuration preset setup (including Node/NPM runtime, Git ignore/hooks, TypeScript, Oxlint, Oxfmt, EditorConfig, Renovate, Changesets, and VSCode).
• A welcoming environment for users and contributors with the continuous integration setup, and the creation of README.md, CONTRIBUTING.md, and GitHub template files (including issue and pull request ones), ...
• An optimized development environment with command caching (no build needed if nothing changes).

🚀 Usage

This section introduces the stack essentials by walking through its main commands:

1️⃣ Create the NPM project via the @adbayb/create initializer:

# Npm
npm init @adbayb
# Pnpm
pnpm create @adbayb

2️⃣ Play with available commands (already set up in the generated root package.json):

# Setup initial requirements (including Git hooks installation)
stack install
# Clean the project
stack clean
# Check code health (static analysis including linters and types)
stack check
# Fix auto-fixable issues
stack fix
# Start the project in production mode
stack start
# Build the project in production mode
stack build
# Build and start the project in development mode
stack watch
# Test the code execution
stack test
# Log, version, and publish package(s)
stack release

3️⃣ Enjoy!

🌍 Ecosystem

Available configurations

• @adbayb/stack/oxlint to align logical and stylistic rules across projects.
• @adbayb/stack/oxfmt to align code formatting conventions across projects.
• @adbayb/stack/typescript to align type checking and processing across projects.

Agent skills

@adbayb/stack ships four Agent Skills for coding agents:

• software-design: design and write clean, testable code; the single source of the design rules and glossary.
• software-audit: audit code or pull requests against the software-design rules (depends on software-design).
• skill-design: design and write skills with one shared anatomy, plus agent instructions such as AGENTS.md; the single source of the writing rules.
• skill-audit: audit and score skills and agent instructions such as AGENTS.md against the skill-design rules (depends on skill-design and Anthropic skill-creator for skill evaluation).

With pnpm 12.11.0 or later, install the package as a direct dependency and approve its skills:

pnpm add -D @adbayb/stack
pnpm approve

If the package is already installed, run pnpm approve. Select @adbayb/stack to approve all four skills; pnpm records the approval in pnpm-workspace.yaml. pnpm links skills into existing agent skill directories by default. To choose a directory explicitly, configure:

skills:
    dirs:
        - .agents/skills

Links use names such as pnpm-@adbayb+stack-software-design. Global installs and pnpm dlx do not link skills.

For older pnpm versions or global installation, install from the repository with:

pnpm dlx skills add adbayb/stack --skill software-design -g
pnpm dlx skills add adbayb/stack --skill software-audit -g
pnpm dlx skills add adbayb/stack --skill skill-design -g
pnpm dlx skills add adbayb/stack --skill skill-audit -g

Use pnpm dlx rather than npx: the repo's devEngines gate accepts pnpm only.

In this repository, stack/skills/ is the published source and .agents/skills is a relative symlink to it, so local agents use the same files.

Used technologies

• Static code analysis: Oxlint, Oxfmt
• Node package manager: PNPM
• Task orchestration: Turborepo
• Release: Changesets
• Testing: Vitest

Used conventions

• Commits
• Scripts
• File Structure
  • Monorepo-first structure to:
    • Keep a consistent file structure pattern across templates (ease template familiarity and onboarding).
    • Ease examples setup.
    • Not clutter the published package with development-related context, metadata, and artifacts.

🏗️ Architecture

Project creation workflow

flowchart TD
    N("npm init @adbayb"):::strokeWidth -- Runs --> C("@adbayb/create"):::strokeWidth
    C -- Runs --> S("@adbayb/stack create"):::strokeWidth
    S -- "Scaffolds (via template and shared configurations)" --> P("New project"):::strokeWidth
    style C fill:#daf2d7,stroke:#90cf8e
    style S fill:#daf2d7,stroke:#90cf8e
    classDef strokeWidth stroke-width:3px

✍️ Contribution

We're open to new contributions, you can find more details here.

📖 License

MIT