# Getting Started This quick start takes you from an empty terminal to a **spec that is ready to build**, and then on to a verified, archived change — all driven through your AI agent's slash commands. Reaching a ready spec takes about ten minutes; shipping the change takes as long as the work does. New to the terms "spec" or "SDD"? Don't worry — you don't need a computer science degree to follow this page. Read on, and every unfamiliar word gets explained the first time it shows up. ::: info Before you begin Forge configures the AI coding agents you already have. It is not an agent installer or a hosted service; it sends anonymous usage/error telemetry (see [Installation](/installation#telemetry) for details and how to opt out). If you have not installed the binary yet, see [Installation](/installation). Bringing an existing Spec-Kit or OpenSpec project? Start with the [Migration Importer](/features/migration) instead of `init`. ::: ::: tip What leaves your machine (and what does not) Forge has **no model of its own** and never enters the inference loop — meaning Forge itself never reads or writes a single line of your code, and never talks to an AI provider on its own. **Forge itself sends nothing to any AI provider** — it only reads your local repository and Git remote to learn the project's identity (its name, its host, that kind of thing), and that is all. The actual AI work — the thinking, the code generation, and anything sent to a model — happens inside **the agent you configure** (Claude Code, Cursor, whichever you use), under **that provider's terms**, not Forge's. Pick your agent and model provider deliberately, and make sure your team understands this data flow (EU AI Act Article 4, AI literacy). The full regulatory posture is in [EU AI Act Position](/compliance/eu-ai-act). ::: ## The shape of the journey ```mermaid flowchart LR I[Install] --> C[Configure agents] --> N[Init project] N --> F[Set foundations] --> R[Get a spec ready] --> S[Build, verify, deliver] --> D[Dashboard & metrics] ``` In plain words, that diagram says: you install one small program once, point it at the AI tools you already use, tell it a bit about your project's ground rules, then for every new feature you write a short plan (a "spec"), get it checked, build it, verify it actually works, and ship it — with a dashboard showing you the whole trail afterward. Steps 1 to 4 are one-time setup — you do them once per machine and once per project, then mostly forget about them. Step 5 is the heart of Forge — turning an idea into a **ready spec**, something precise enough that an AI agent (or a teammate) can build it without guessing. Step 6 builds that spec into verified code and opens the merge or pull request on your git host. ::: details Curious what "SDD" means? SDD stands for **Spec-Driven Development**. The idea is simple: instead of asking an AI agent to "just build the feature" and hoping it guesses your intent correctly, you first write a short, structured description — a **spec** — of what the feature must do, how it will be tested, and what it must never break. The agent then builds *against* that spec, and Forge checks the result *against* that same spec. It is the same instinct behind writing a blueprint before building a house, or a test plan before shipping a product: the extra ten minutes up front saves hours of rework later. See [The Workflow](/guide/workflow) for the full picture. ::: ## 1. Install the binary Maistik Forge Kit is licensed software. With a license, your GitHub account has access to the private release repository: download the archive for your platform, extract it, and put `forge` on your `PATH`. ```sh # macOS (Apple silicon), adjusted to the release you downloaded tar -xzf forge_Darwin_arm64.tar.gz && sudo mv forge /usr/local/bin/forge ``` ::: details New to the terminal? Here's what that command actually does - A **binary** is just the ready-to-run program itself — no installer, no setup wizard, a single file called `forge`. - `tar -xzf forge_Darwin_arm64.tar.gz` **unpacks** the archive you downloaded (like unzipping a `.zip` file, just for `.tar.gz` files, common on macOS and Linux). - `sudo mv forge /usr/local/bin/forge` **moves** that unpacked program into a folder your computer already knows to look in whenever you type a command — that folder is your `PATH`. `sudo` just means "do this with administrator permission," since `/usr/local/bin` is a system folder. Your machine will ask for your password. - After this, typing `forge` anywhere in your terminal runs the program, the same way typing `git` or `ls` does. ::: See [Installation](/installation) for every platform and for checksum verification, and [Pricing](/pricing) if you do not have a license yet. Homebrew and Scoop are **not yet published**. Confirm the binary itself is healthy — this runs an in-process smoke test and does not need a project to check yet: ```sh forge doctor --selftest ``` ::: tip Pro tip: run `doctor --selftest` before anything else If this command fails, nothing downstream will work — there's no point troubleshooting `forge init` or an agent integration until this one passes. It only checks that the `forge` program itself is intact; it does not touch your project or the network. ::: ## 2. Configure your agents Detect and configure the AI coding agents already on your machine: ```sh forge install ``` Forge detects installed agents automatically (it never asks you to name them), backs up any existing configuration first, and is idempotent — meaning you can run it again and again, and it will not create duplicates or break anything each time. Every command below becomes available inside each configured agent as a `/forge.` slash command — the same kind of `/command` shortcut you already type into Claude Code, Cursor, or whichever assistant you use, except now it triggers a Forge phase instead of a built-in feature of that tool. ::: tip Preview first Not sure what will change? Run `forge install --dry-run` to see exactly what Forge would write, without touching anything. A **dry run** means Forge shows you its plan on screen but makes zero changes to your disk — a safe way to check before committing to anything, and a pattern you'll see again throughout this guide. ::: See [Supported Agents](/guide/agents) for the full list and per-agent notes, and [Skills: Registry & Discovery](/features/skills) for how Forge equips each agent with the right capabilities for the task at hand. ## 3. Initialize the project From your project root, run the per-repository wizard: ```sh forge init ``` This creates the `.forge/` directory — the home for your specs, changes, and memory. Think of it as the project's own filing cabinet: every plan you write, every decision you make, and every change you ship gets a paper trail inside this one folder, right next to your code. For a non-interactive setup, pass `--yes` to accept sensible defaults. See [Project Structure](/guide/project-structure) for a tour of what lands where, and [Configuration](/guide/configuration) to tune `.forge/config.yaml`. ::: tip Commit `.forge/` Commit the `.forge/` directory so your whole team shares the same specs, changes, and project memory. In other words: treat it like source code, not like a personal scratch folder — it belongs in Git, right alongside the code it describes, so a teammate (or an AI agent working on a different machine) sees the exact same history you do. See [Best Practices](/guide/best-practices). ::: With the project initialized, confirm everything is actually ready — agents detected, `.forge/` writable, and every dependency (Node, Engram, …) installed: ```sh forge doctor ``` A clean report means agents are configured, the project is initialized, and every dependency is present. Anything else is flagged with a fix hint — pass `--fix` to have Forge attempt the failed and warning dependency checks automatically: ```sh forge doctor --fix ``` ## 4. Set your foundations (run once) Before writing feature specs, establish the **standing truth** your changes are measured against — the ground rules every future feature has to respect, so you're not re-deciding the same principles every single time you build something new. The [foundation phases](/guide/foundations) run once and set those ground rules: ```text /forge.constitution define non-negotiable principles and constraints /forge.security define the security baseline /forge.infra define the infrastructure baseline /forge.brand define brand identity and voice /forge.design define the design system ``` ::: tip The `forge init` wizard already asked you this The wizard's **Foundation** step lets you check off whichever of these five you want scaffolded right away. Whatever you checked, `forge init` prints the exact `/forge.*` command for each one as your next steps — copy them straight from that output rather than retyping the list above. Leave one unchecked and just run its command later, whenever you get to it. ::: ::: details What is a "constitution" in this context? It has nothing to do with government. Think of it as your team's **non-negotiable rulebook** — the handful of things every feature must respect no matter what: "we never log customer emails in plain text," "every public endpoint needs rate limiting," "we support the last two major browser versions," that sort of thing. Once written, Forge checks every future spec against it automatically, the same way a building inspector checks every new construction against the local building code — not by re-reading the whole code every time, but by checking the specific plan against the specific rules that apply. ::: At minimum, write a **constitution**. It is not just documentation — constitution conflicts are blocking findings that **cap your quality score** (more on that score in a moment), so a stale or missing constitution is a standing penalty on every spec you write afterward. See [Change Governance](/features/governance) for how foundations are enforced, and [Persistent Memory](/concepts/memory) for how Forge remembers decisions across changes. ## 5. Get your first spec ready This is the core loop — the part of Forge you'll come back to for every single feature, bug fix, or change you make from now on. A change flows through the [SDD spine](/guide/workflow); the first four phases take a raw idea and turn it into a **ready spec** before a line of code is written. ```mermaid flowchart LR E[/forge.explore/] --> P[/forge.propose/] P --> S[/forge.specify/] --> C[/forge.clarify/] --> Ready([spec ready]) ``` In plain words: you optionally look around the codebase first, then write down what you want to build, turn that into a precise requirements document, tighten up anything ambiguous, and only then does Forge consider the spec "ready." ::: tip In practice, `/forge.new` and `/forge.continue` drive this for you The four commands below are shown separately so you know what each phase actually produces, but you rarely type all of them by hand. Run `/forge.new ` to kick things off — it explores if warranted, then drafts the proposal — and then `/forge.continue` to walk through the rest, one phase at a time, resolving whichever comes next on its own. See [Entry commands](/guide/commands#entry-commands) for the full picture, including `/forge.ff` for blasting through all four planning phases back-to-back. ::: **Explore** (optional) — investigate the codebase and weigh approaches before committing: ```text /forge.explore how should we add rate limiting to the public API? ``` **Propose** — capture the intent, scope, and approach as a change proposal: ```text /forge.propose add rate limiting to the public API ``` **Specify** — write the delta spec: requirements in RFC-2119 language (MUST/SHOULD/MAY) with Given/When/Then acceptance scenarios: ```text /forge.specify ``` ::: details What do "RFC-2119" and "Given/When/Then" actually mean? Neither one is as intimidating as it sounds. - **RFC-2119 language** is just a convention for writing requirements so there's zero ambiguity about how strict a rule is. `MUST` means non-negotiable. `SHOULD` means strongly recommended, with room for a documented exception. `MAY` means genuinely optional. Instead of a requirement that vaguely says "the API should probably be rate limited," you get "the API **MUST** reject requests past 100/minute per key" — something a human or an AI agent can build and test without guessing what you meant. - **Given/When/Then** is a simple template for describing a test scenario in plain English: *Given* the starting condition, *When* an action happens, *Then* what should be true afterward. For example: *Given a user has made 100 requests this minute, When they make a 101st request, Then the API returns a 429 error.* No code — just a precise, testable sentence. Together, these two conventions are what let an AI agent build a feature correctly on the first attempt more often, and let Forge check "is this actually done?" automatically instead of by eyeballing it. ::: **Clarify** — resolve ambiguity and strengthen the spec; answers are encoded back into it: ```text /forge.clarify ``` ::: tip Reuse what you already decided Run `/forge.recall` before specifying to surface prior specs and decisions relevant to this change. It is advisory — it informs the spec, it never blocks — so think of it as Forge tapping you on the shoulder with "hey, didn't we already decide something like this six weeks ago?" before you re-litigate a settled question. See [Persistent Memory](/concepts/memory). ::: ### Is the spec actually ready? "Ready" is not a feeling — Forge measures it, so you're never left guessing whether you've written "enough" spec. Score the spec against the reproducible 100-point rubric: ```sh forge analyze ``` A ready spec has a complete skeleton (every required section filled in), clear requirements, a scenario for every requirement, and no constitution conflict. See [Quality Gates](/features/quality) for the full rubric, and check `/forge.status` any time to see where the change sits on the spine. ::: tip Pro tip: don't chase a perfect score The rubric exists to catch real gaps — a missing scenario, a vague requirement, a forgotten security consideration — not to be gamed for a round number. Once `forge analyze` reports the spec is ready, move on to building. You can always tighten a spec later if reality teaches you something new. ::: ## 6. From a ready spec to a shipped change With the spec ready, build it. Strict TDD is the default, so tests come first — meaning the agent writes the test that proves a feature works *before* it writes the feature itself, the same discipline good human engineers already practice. If a change can't be verified this way, Forge will tell you rather than let it slip through unverified. ```mermaid flowchart LR PL[/forge.plan/] --> T[/forge.tasks/] --> IM[/forge.implement/] IM --> V[/forge.verify/] --> A[/forge.archive/] --> D[forge deliver] ``` ```text /forge.plan write plan.md — the architecture and decisions /forge.tasks break the plan into an ordered, honest checklist /forge.implement build the tasks, tests first /forge.verify check the work against its acceptance scenarios /forge.archive merge the delta spec into canonical specs; seal the audit trail ``` As with the earlier phases, `/forge.continue` from the previous step already walked you through `plan` and `tasks` — `/forge.implement` is usually the first command in this block you actually type by hand. Implementation and verification run inside the **enforced harness** — think of it as the safety rails and seatbelt on an otherwise very fast, very capable car: the AI agent still does the driving, but it cannot run through a red light without something stopping it and telling a human. - The [Guardrails Gate](/harness/guardrails) blocks a change that leaks secrets, PII, or prompt-injection strings — the automated equivalent of a colleague catching an API key accidentally committed in a pull request. - The [Verify Circuit-Breaker](/harness/circuit-breaker) stops runaway verify/implement loops before they burn time and budget — if the agent gets stuck retrying the same failing test over and over, this cuts it off instead of letting it spin forever. - The [Spend Budget](/harness/budget) enforces a per-change ceiling on tokens, cost, and tool calls, so one runaway change can't quietly burn through your AI provider bill. You can also verify directly from the terminal against a named change: ```sh forge verify --change add-rate-limiting ``` Add `--isolated` and verification runs against an **ephemeral copy** of the repository — committed files plus your uncommitted edits — so a test or build the agent just wrote cannot corrupt your working tree. "Ephemeral" here just means temporary: a disposable copy Forge throws away afterward, not your real project files. ```sh forge verify --change add-rate-limiting --isolated ``` That isolates the filesystem, not processes or the network. See [Isolated Verification](/harness/isolation) for exactly what it does and does not contain. ::: warning Honest task status A task is only `done` when its acceptance scenarios pass under verify — not when the agent merely says it finished. `archive` is blocked while any task is still `blocked` or not done, so a green archive genuinely means the work is complete, and nobody has to take an AI agent's word for it. ::: ### Hand the loop off (optional) If you want the implement/verify cycle driven for you, `forge run` executes an agent command repeatedly and **stops the moment an enforced gate opens**, escalating to a human rather than retrying: ```sh forge run --cmd 'claude -p "work the next task in tasks.md"' # dry run — nothing executes forge run --cmd '…' --change add-rate-limiting --max-iterations 3 --yes # execute ``` ::: danger Forge has no model of its own Forge cannot write code — it has no LLM (large language model) of its own. You supply the executor with `--cmd` — that's the actual AI agent command that does the thinking — and Forge is just the harness around it, watching and stopping it when a gate trips. This is a deliberate, bounded exception to Forge's usual "configure the loop, don't fire it" posture: dry run is the default (nothing runs until you explicitly say so with `--yes`), `--max-iterations` defaults to 5 with a hard ceiling of 50, and finishing the cap counts as an escalation to a human, not a success. See [Bounded Autonomous Run](/harness/autonomous-run). ::: ### Ship it to your git host Forge resolves which host this repo lives on — GitLab, GitHub, Gitea, Bitbucket — and speaks that host's terminology (so it says "pull request" on GitHub and "merge request" on GitLab, matching what you'd expect). Check what it resolved, then open the change request: ```sh forge provider # what host is this, and which CLI? forge deliver --dry-run # preview the exact glab/gh command forge deliver --label forge --base main # open the merge or pull request ``` The body is assembled from the change's `proposal.md` plus its task list, and delivery **refuses while any task is not done** (`--allow-incomplete` is the deliberate override, e.g. for an early `--draft`). You can also export the remaining tasks as issues on the same host: ```sh forge issues create --change add-rate-limiting --dry-run ``` See [Git Providers & Related Repos](/features/providers). If the work spans sibling repositories, `forge workspace` shows which repos a change touches, and `--workspace` runs `deliver`/`issues create` across all of them — see [Multi-Repo Workspace](/features/workspace). ## 7. View your dashboard Forge generates a live, self-contained dashboard from your `.forge/` state — no external service, no account to create, it just reads the same files sitting in your project. Serve it locally while you work: ```sh forge docs serve ``` This opens a browser view of your specs, quality scores, task status, budget, breaker state, and the attributed [session timeline](/harness/timeline) — a readable, visual version of everything the CLI has been tracking all along. See the [dashboard overview](/features/dashboard) for a tour. Want to watch the whole lifecycle run end to end against a sample project first, with nothing at stake? Try [The Sandbox](/guide/sandbox). The dashboard shows you one change. To ask whether the **harness itself** is earning its keep — across every feature you've ever shipped with it, not just the one you're looking at — roll the same recorded state up across every change, active and archived: ```sh forge metrics # readable rollup forge metrics --json # stable machine output for dashboards or CI ``` Verify pass rate, breaker openings, spend, waived secscan findings, timeline volume, contributors — the numbers that answer "is this actually helping, or just adding ceremony?" It adds no instrumentation of its own; it simply reads the state the gates already write as they run, so there's no separate tracking system to trust or misconfigure. See [Harness Metrics](/harness/metrics), and [Harness as MCP](/harness/mcp) if you would rather your agent query all of this directly with `forge mcp serve`. ::: tip Pro tip: `forge metrics` is your best argument in a "is this worth it?" conversation If a teammate or manager is skeptical about adding process to a fast-moving team, this is the command that turns the question into data instead of opinion — actual verify pass rates and actual time-to-ship numbers, not a guess. ::: ## Explore related topics Everything the quick start touched, grouped for a deeper read: **Agents & skills** - [Supported Agents](/guide/agents) — which agents Forge configures and how. - [Skills: Registry & Discovery](/features/skills) — how agents get the right capabilities. **The harness (enforced gates)** - [Enforcement Doctrine](/harness/overview) — what is enforced vs. advisory, and why. - [The Guardrails Gate](/harness/guardrails) · [Verify Circuit-Breaker](/harness/circuit-breaker) · [Spend Budget](/harness/budget) · [Session Timeline](/harness/timeline) **The harness (everything else)** - [Bounded Autonomous Run](/harness/autonomous-run) — `forge run`, and why it stops instead of retrying. - [Isolated Verification](/harness/isolation) — verify against an ephemeral copy, not your tree. - [Harness Metrics](/harness/metrics) — whether the gates are earning their keep. - [Harness as MCP](/harness/mcp) — let an agent query the gates (queryable, not enforcing). **Delivery & multi-repo** - [Git Providers & Related Repos](/features/providers) — `forge provider`, `deliver`, `issues create`. - [Multi-Repo Workspace](/features/workspace) — siblings, spanning changes, cross-repo delivery. - [Repo Adaptivity](/features/adaptivity) — the profile forge builds of your repository. **Specs, quality & governance** - [The Workflow](/guide/workflow) — the full SDD spine and adaptive depth. - [Quality Gates](/features/quality) — the 100-point score that defines "ready". - [Change Governance](/features/governance) — how foundations and gates hold the line. **Foundations & memory** - [Foundation Phases](/guide/foundations) — constitution, security, infra, brand, design. - [Persistent Memory](/concepts/memory) · [Drift & Reconcile](/concepts/drift-and-reconcile) **More** - [Migration Importer](/features/migration) — bring an existing Spec-Kit or OpenSpec project. - [The Sandbox](/guide/sandbox) — see the whole lifecycle run in one command. - [Command Reference](/guide/commands) · [The forge CLI](/reference/cli) · [Configuration](/guide/configuration) Stuck anywhere on this page, or something didn't behave the way it's described here? [Open an issue on GitHub](https://github.com/Maistik-Studio/forge-kit/issues) — it's the fastest way to reach the people building this.