# Quickstart {#quickstart}



## Initialize a Workspace {#initialize-a-workspace}


```bash
cd your-project
scafld init
```

`init` creates `.scafld/` and installs the managed core bundle under
`.scafld/core/`. Project prompt overrides are optional; add files under
`.scafld/prompts/` only when you need to customize the built-in prompts.

For a new repository, generate a grounded config proposal before the first
serious spec:

```bash
scafld config
```

Review `.scafld/config.proposed.yaml`, follow its `agent_instructions`, and
copy only verified runtime policy into `.scafld/config.yaml`. Put agent-facing
guidance in `AGENTS.md`, `CLAUDE.md`, `.claude/rules`, or project prompts
instead of inventing config fields.


## Create a Draft Spec {#create-a-draft-spec}


```bash
scafld plan add-auth --title "Add JWT authentication" --size medium --risk high --command "npm test"
```

This writes `.scafld/specs/drafts/add-auth.md`. Open the file and tighten the
human-readable contract: objective, scope, context, phase changes, and
acceptance criteria.


## Harden Before Approval {#harden-before-approval}


```bash
scafld harden add-auth
```

The command enters HARDEN MODE and records a hardening round in the spec. Use
the printed prompt to attack the plan before execution:

- why the plan exists and which shared core/app contract owns the behavior
- whether API/MCP/CLI/provider/docs surfaces stay light adapters
- whether scope, migration, and cutover claims are honest
- whether paths and commands are real
- whether acceptance criteria run at the right phase
- whether rollback or repair is realistic

When the answers are worked into the spec:

```bash
scafld harden add-auth --mark-passed
```

Hardening is not ceremony. It is the step that keeps the agent from discovering
the definition of done while already changing code.


## Approve and Build {#approve-and-build}


```bash
scafld validate add-auth
scafld approve add-auth
scafld build add-auth
```

`build` activates approved work, opens the current phase, and projects the
current state back into the spec. The first build does not run future
acceptance. Read the handoff, implement the phase, then run
`scafld build add-auth` again to record evidence and advance.


## Run Adversarial Review {#run-adversarial-review}


Use an external challenger for real work:

```bash
scafld review add-auth --provider codex
scafld review add-auth --provider claude
scafld review add-auth --provider gemini
scafld review add-auth --provider command --provider-command "./reviewer"
scafld review add-auth --print-context
```

With no provider flag, scafld uses `--provider auto`. If scafld can infer the
current host agent, it prefers the other installed challenger, can use Gemini as
another external challenger, and fails closed when only the host provider is
available. If no external challenger is installed, review fails closed. Use
`--provider local` only for development smoke tests; local verdicts cannot
satisfy `finalize`.

`--print-context` shows the exact deterministic brief before you spend a review
run.


## Finalize {#finalize}


```bash
scafld finalize add-auth
```

`finalize` consumes the passing review evidence, reruns deterministic acceptance,
signs the receipt, and archives the spec without another model call. If review
returns a blocking finding, repair the work, rerun `build` as needed, then rerun
`review`.


## Inspect State {#inspect-state}


```bash
scafld status add-auth
scafld list
scafld report
```

The lifecycle stays deliberately small:

```text
draft -> harden -> approved -> active -> review -> completed
```


## Next Steps {#next-steps}


- [Lifecycle](https://auscaster.com/scafld/docs/lifecycle.md) -- states and transitions
- [Spec Schema](https://auscaster.com/scafld/docs/spec-schema.md) -- Markdown spec grammar
- [CLI Reference](https://auscaster.com/scafld/docs/cli-reference.md) -- command and flag surface
- [Review](https://auscaster.com/scafld/docs/review.md) -- adversarial review gate