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.

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 for details and how to opt out). If you have not installed the binary yet, see Installation. Bringing an existing Spec-Kit or OpenSpec project? Start with the Migration Importer instead of init.

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.

The shape of the journey

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.

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 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.

# macOS (Apple silicon), adjusted to the release you downloaded
tar -xzf forge_Darwin_arm64.tar.gz && sudo mv forge /usr/local/bin/forge

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 for every platform and for checksum verification, and 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:

forge doctor --selftest

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:

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.<name> 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.

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 for the full list and per-agent notes, and Skills: Registry & Discovery 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:

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 for a tour of what lands where, and Configuration to tune .forge/config.yaml.

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.

With the project initialized, confirm everything is actually ready — agents detected, .forge/ writable, and every dependency (Node, Engram, …) installed:

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:

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 run once and set those ground rules:

/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

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.

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 for how foundations are enforced, and Persistent 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; the first four phases take a raw idea and turn it into a ready spec before a line of code is written.

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."

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 <what you're building> 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 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:

/forge.explore how should we add rate limiting to the public API?

Propose — capture the intent, scope, and approach as a change proposal:

/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:

/forge.specify

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:

/forge.clarify

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.

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:

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 for the full rubric, and check /forge.status any time to see where the change sits on the spine.

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.

/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 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 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 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:

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.

forge verify --change add-rate-limiting --isolated

That isolates the filesystem, not processes or the network. See Isolated Verification for exactly what it does and does not contain.

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:

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

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.

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:

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:

forge issues create --change add-rate-limiting --dry-run

See Git Providers & Related Repos. 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.

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:

forge docs serve

This opens a browser view of your specs, quality scores, task status, budget, breaker state, and the attributed session timeline — a readable, visual version of everything the CLI has been tracking all along. See the dashboard overview 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.

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:

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, and Harness as MCP if you would rather your agent query all of this directly with forge mcp serve.

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 — which agents Forge configures and how.
• Skills: Registry & Discovery — how agents get the right capabilities.

The harness (enforced gates)

• Enforcement Doctrine — what is enforced vs. advisory, and why.
• The Guardrails Gate · Verify Circuit-Breaker · Spend Budget · Session Timeline

The harness (everything else)

• Bounded Autonomous Run — forge run, and why it stops instead of retrying.
• Isolated Verification — verify against an ephemeral copy, not your tree.
• Harness Metrics — whether the gates are earning their keep.
• Harness as MCP — let an agent query the gates (queryable, not enforcing).

Delivery & multi-repo

• Git Providers & Related Repos — forge provider, deliver, issues create.
• Multi-Repo Workspace — siblings, spanning changes, cross-repo delivery.
• Repo Adaptivity — the profile forge builds of your repository.

Specs, quality & governance

• The Workflow — the full SDD spine and adaptive depth.
• Quality Gates — the 100-point score that defines "ready".
• Change Governance — how foundations and gates hold the line.

Foundations & memory

• Foundation Phases — constitution, security, infra, brand, design.
• Persistent Memory · Drift & Reconcile

More

• Migration Importer — bring an existing Spec-Kit or OpenSpec project.
• The Sandbox — see the whole lifecycle run in one command.
• Command Reference · The forge CLI · Configuration

Stuck anywhere on this page, or something didn't behave the way it's described here? Open an issue on GitHub — it's the fastest way to reach the people building this.