baseline

One command to give your entire team the same AI tools, skills, and working rules — so anyone can pick up where someone else left off.

Quick start

For a non-technical, step-by-step Windows installation, see the Windows installation manual. For all platforms and troubleshooting, see the cross-platform installation requirements.

npm install -g baseline-ai
baseline install

That's it. Your machine now has the same setup as every other team member.

To update an existing installation, follow the Base AI update guide.

What it installs

| Component | Where | |-----------|-------| | AI skills (review, design, git…) | ~/.claude/skills/ · ~/.opencode/skills/ · ~/.kiro/skills/ | | Team standards block | ~/.claude/CLAUDE.md · ~/.opencode/AGENTS.md · ~/.kiro/steering/baseline.md | | Gentle-AI ecosystem | global | | Engram MCP wiring (if installed) | per AI tool via engram setup | | Git hooks (global pre-push, advisory-only) | ~/.baseline/hooks/ via core.hooksPath | | OpenSpec change-tracking structure | ./openspec/ in the project | | Corporate skills from baseline-cloud (when configured) | ~/.kiro/steering/bl-*.md — synced automatically | | Background watcher for Kiro credit tracking | launchd (macOS) / cron (Linux) — installed automatically | | OpenSpec lifecycle synchronization | Windows Task Scheduler / macOS LaunchAgent (every 5 minutes) / Git hooks |

Commands

baseline install                  # auto-detect tools and configure all
baseline install kiro-ide         # configure only Kiro IDE (~/.kiro detected)
baseline install kiro-cli         # configure only Kiro CLI (kiro binary detected)
baseline update                   # pull latest baseline and re-apply standards
baseline status                   # show what's installed and configured
baseline doctor                   # diagnose missing or broken setup — includes Engram check
baseline openspec sync --cwd .    # reconcile active and archived OpenSpec changes
baseline onboard junior           # onboarding guide by level: junior · semi · senior
baseline enroll --status          # inspect opt-in project enrollment
baseline enroll --slug my-project # explicitly enroll this project
baseline enroll --skip             # decline enrollment for this project
baseline enroll --slug my-project --force # retry after a previous skip

# baseline-cloud — connect to your team's self-hosted baseline-cloud server
baseline cloud login              # authenticate (one-time setup)
baseline cloud status             # show connection status and configured server
baseline cloud sync               # download latest corporate skills to ~/.kiro/steering/
baseline cloud logout             # remove saved credentials
baseline cloud kiro-scan          # manually report Kiro session credit usage

# profiles — separate baseline-cloud, Engram and Jira per company
baseline profile list|current     # show profiles and where the active one came from
baseline profile use <name>       # switch the global profile (materializes skills, steering, hooks, MCP into ~/.kiro)
baseline profile pin <name>       # pin this directory (and below) to a profile; stored only in ~/.baseline, never in the repo
baseline profile unpin            # remove the pin for this directory
baseline profile pin <name> --remote [pattern]  # pin by git remote (host or host/owner) instead of by folder
baseline profile pins             # list all directory and remote pins
baseline profile apply            # make Kiro use this project's pinned profile: writes .kiro/settings/mcp.json (Engram + Jira), hidden from git
baseline profile explain          # why this folder resolves to its profile (see docs/guides/profiles.md)

# baseline repo — per-repository skill policy
baseline repo init                # configure which skills are disabled for this repo
baseline repo sync                # sync repo policy from baseline-cloud

OpenSpec automatic synchronization

baseline install creates a project-bound Windows Task Scheduler task or macOS LaunchAgent when run from the canonical project root with openspec/. The macOS agent lives under ~/Library/LaunchAgents, runs at login and every five minutes, and uses the packaged CLI with the project's working directory. It scans active proposals as change.open and archived proposals as change.close. Git hooks also trigger the same best-effort, non-blocking reconciliation immediately after commits.

The reconciler stores crash-safe delivery state in .baseline/openspec-sync.json, so repeated task, agent, and hook runs do not duplicate events. Failed cloud flushes remain pending for retry; do not delete this file during recovery. If synchronization is missing or telemetry was temporarily unavailable, run baseline doctor, repair with baseline install, and retry with baseline openspec sync --cwd .. On macOS, inspect the project agent with launchctl print gui/$(id -u)/<label>; baseline uninstall removes it when run from that project. No global arbitrary-directory job is created. Outside a canonical project root containing openspec/, scheduler installation is skipped with an actionable message; the manual command remains the fallback.

Team workflow

Every change follows ODD (Organic Driven Development):

authorize → explore → classify by size → implement → check → close

ODD keeps understood changes lightweight and gives substantial, authorized work one recoverable feature document. Task size is decided by understanding, risk, and resumability — never by file count. Small, understood work runs inline; the workflow is provided natively by Gentle-AI.

Supported AI tools

| Tool | Skills | Team config | Gentle-AI preset | |------|--------|-------------|-----------------| | Kiro IDE (~/.kiro detected) | ✅ | ✅ ~/.kiro/steering/baseline.md (strict TDD) + statusline sub-agent | performance | | Kiro CLI (kiro binary detected) | ✅ | ✅ same as Kiro IDE (strict TDD) | performance |

Detection is automatic — baseline install reads your environment and configures only the tools that are present.

Skills reference

17 skills are installed across all supported tools. Each skill is invoked with /skill-name inside your AI tool. Click the skill name to see a concrete usage example. Each example shows real prompts and output — not limits on what the skill can do.

Architecture

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /architecture-guidelines | Validate and guide file placement across NestJS hexagonal layers (infrastructure, services, domain). Enforces 7 CI/CD-blocking rules including multi-tenancy isolation, PII protection, and controller/service separation. | /architecture-guidelines quiero crear un servicio que envíe emails cuando se procese un pago exitoso. ¿Dónde va cada archivo? |

Code review

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /judgment-day | Two independent judges review the same code. Only issues both confirm get fixed. | /judgment-day revisa el PR del módulo de pagos | | /comment-writer | Writes warm, direct PR comments — collaborative tone, not accusatory. | /comment-writer este método tiene un N+1 query, ¿cómo lo comento? |

Git & pull requests

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /chained-pr | Splits oversized PRs (400+ lines) into a reviewable sequence. | /chained-pr tengo 800 líneas de refactor en el módulo de usuarios | | /work-unit-commits | Plans commits as self-contained reviewable units before pushing. | /work-unit-commits implementé notificaciones, auth y la integración |

Security & conflicts

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /conflict-resolver | Analyze and resolve git merge conflicts using deep reasoning. Classifies each conflict (AUTO / PREFER-OURS / PREFER-THEIRS / MERGE / AMBIGUOUS) and shows a diff preview before applying. | /conflict-resolver |

Documentation

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /changelog-generator | Transforms git commits into polished changelogs and release notes. | /changelog-generator genera las release notes para v2.1.0 | | /cognitive-doc-design | Designs guides, READMEs, and RFCs that minimize cognitive load. | /cognitive-doc-design necesito un README para el microservicio de pagos |

Design & frontend

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /archify | Creates polished, validated architecture, workflow, sequence, data-flow, and lifecycle diagrams as explorable standalone HTML, with runtime renderers, schemas, and export support. | /archify crea un diagrama de arquitectura para el flujo de pagos | | /frontend-design | Builds production-grade web UIs — avoids generic AI aesthetics. | /frontend-design página de login para un SaaS B2B, estilo profesional | | /interface-design | Builds dashboards, admin panels, and internal tools. | /interface-design dashboard de métricas de pagos para operaciones | | /tailwind-design-system | Builds scalable design systems with Tailwind CSS v4: tokens, components, patterns. | /tailwind-design-system sistema de diseño para suite de productos internos |

Testing

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /go-testing | Applies focused Go testing patterns: coverage, TUI flows, teatest, golden files. | /go-testing necesito testear un handler gRPC con dependencias externas |

GitHub

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /issue-creation | Creates GitHub issues with full context: steps to reproduce, impact, expected behavior. | /issue-creation el checkout falla en Safari cuando hay 2+ items |

Skills meta

| Skill | What it does | Example prompt | |-------|-------------|----------------| | /skill-creator | Creates new LLM-first skills with valid SKILL.md frontmatter. | /skill-creator quiero una skill para nuestro proceso de deploy | | /skill-improver | Audits and refactors existing SKILL.md files: normalize conventions, improve quality. | /skill-improver revisa la skill de branch-pr | | /skill-registry | Rebuilds the skill index after adding or changing skills. | /skill-registry |

Integrations

Git workflow

baseline install installs a global pre-push git hook. It is advisory-only and never blocks a push.

Re-run baseline install after updating baseline to refresh the hook.

Guide: → docs/guides/git-workflow.md

baseline-cloud (corporate skills and Kiro credit tracking)

baseline-cloud is built into the CLI — no separate install needed. If your team runs a self-hosted baseline-cloud server, connect once and everything syncs automatically.

One-time setup:

baseline cloud login --server https://your-baseline-cloud.com --token <your-token>
baseline cloud status             # confirm connection
baseline cloud sync               # pull corporate skills immediately

What happens automatically after login:

• baseline install syncs corporate skills from baseline-cloud to ~/.kiro/steering/bl-*.md
• Kiro IDE runs baseline cloud sync at the start of every session (via steering file)
• A background watcher (launchd on macOS, cron on Linux) scans ~/.kiro/sessions/ every 5 minutes and reports credit usage to baseline-cloud

All baseline-cloud commands:

| Command | Description | |---------|-------------| | baseline cloud login --server <url> --token <token> | Authenticate with your baseline-cloud server. Credentials saved to ~/.baseline/cloud.json. | | baseline cloud status | Show configured server URL and token prefix. | | baseline cloud sync | Download all corporate skills to ~/.kiro/steering/bl-*.md. Removes stale skills automatically. | | baseline cloud logout | Remove saved credentials. | | baseline cloud kiro-scan | Manually scan ~/.kiro/sessions/ and report credit usage to baseline-cloud. |

Repository skill policy:

Admins can disable specific skills per project in the baseline-cloud dashboard (Admin → Projects → skill policy). The policy syncs automatically via baseline cloud kiro-scan and can be applied manually:

# Run once per repository to configure local overrides:
baseline repo init

# Apply the cloud policy to the current workspace immediately:
baseline repo sync

Policy is stored in three layers, applied in order:

1. Cloud (admin-managed, immutable per client) — baseline-cloud dashboard
2. Repo (committed, shared with team) — .baseline/config.json
3. Local (personal overrides, gitignored) — .baseline/config.local.json

The merged result is written to .kiro/steering/baseline-repo-policy.md in the workspace, which Kiro reads automatically. Kiro enforces disabled skills without executing them.

Full guide: → docs/guides/baseline-cloud.md

Project enrollment

Enrollment is explicitly opt-in. baseline install never writes a project identity and never enrolls the current directory, which makes global installation safe from an arbitrary working directory.

Run baseline enroll --status to inspect the local state. --skip records a decision not to enroll; --force allows changing that decision. When cloud credentials are unavailable or the server rejects the project, Base AI keeps a retryable local state and reports the cloud failure instead of claiming successful enrollment. Enrollment files are resolved at the repository root, including when run from a nested directory or with --cwd.

Base AI includes telemetry, project enrollment, ODD lifecycle, skills, hooks, session tracking, and cloud skill synchronization in the same CLI. These features work locally without cloud credentials; cloud delivery is enabled after baseline cloud login.

Requirements

• Node.js >= 22.0.0 (required by Charcoal)
• At least one supported AI tool installed

Prerequisites — download links

| Tool | Platform | Download | |------|----------|----------| | Node.js 22+ | all | https://nodejs.org/en/download | | nvm (Node version manager) | macOS/Linux | https://github.com/nvm-sh/nvm | | nvm-windows | Windows | https://github.com/coreybutler/nvm-windows/releases | | npm | all | ships with Node.js — https://docs.npmjs.com/downloading-and-installing-node-js-and-npm | | Git | all | https://git-scm.com/downloads | | Go (for Gentle-AI/Engram from source) | Windows | https://go.dev/dl/ | | Homebrew (for Gentle-AI/Engram) | macOS | https://brew.sh |

Per-OS notes

• macOS: Node.js 22.0.0+ via nvm, Homebrew, or the official installer. Kiro IDE/CLI is detected automatically.
• Linux: Node.js 22.0.0+ (via nvm or the official installer) and a supported AI tool. The optional Kiro watcher uses cron.
• Windows: Node.js 22.0.0+ (nvm-windows or the official installer), Git for Windows, and at least one supported AI tool. Go is only needed to build Gentle-AI/Engram from source. Native Base AI installation does not require Bash or WSL; Git hooks use POSIX sh supplied by Git for Windows and skip safely when Node is unavailable.

CI — publish on release

The workflow in .github/workflows/publish.yml runs lint, build, and publish automatically when you create a GitHub release. Add your NPM_TOKEN as a repository secret to enable it.