Skip to content
Skills Library
Programming · Learning & explanation

getting-started

/getting-started

Onboard a new or stuck user onto forgectl — the spec-driven development harness. Explains the mental model (specs are the source of truth; forgectl is a state-machine driver, not a code generator), installation, how to configure .forgectl/config, how to pick a starting phase for a new product or an existing codebase, how to drive the advance/status/eval loop, and which phase skill to use for each step. Use when someone is new to forgectl, asks how to get started or how to use it, finds it hard to use, or asks how the workflows/phases fit together.

Repository
forgectl ↗
Licence
MIT
Last repository change
08.08.2026

Assessment and security

91/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content31 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
4
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 08.08.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Onboard a new or stuck user onto forgectl — the spec-driven development harness. Explains the mental model (specs are the source of truth; forgectl is a state-machine driver, not a code generator), installation, how to configure .forgectl/config, how to pick a starting phase for a new product or an existing codebase, how to drive the advance/status/eval loop, and which phase skill to use for each step. Use when someone is new to forgectl, asks how to get started or how to use it, finds it hard to use, or asks how the workflows/phases fit together.

Original author description

Onboard a new or stuck user onto forgectl — the spec-driven development harness. Explains the mental model (specs are the source of truth; forgectl is a state-machine driver, not a code generator), installation, how to configure .forgectl/config, how to pick a starting phase for a new product or an existing codebase, how to drive the advance/status/eval loop, and which phase skill to use for each step. Use when someone is new to forgectl, asks how to get started or how to use it, finds it hard to use, or asks how the workflows/phases fit together.

How it works

SKILL.md has no level-two headings · 264 lines, 2,368 words

SKILL.md preview
---
name: getting-started
description: Onboard a new or stuck user onto forgectl — the spec-driven development harness. Explains the mental model (specs are the source of truth; forgectl is a state-machine driver, not a code generator), installation, how to configure .forgectl/config, how to pick a starting phase for a new product or an existing codebase, how to drive the advance/status/eval loop, and which phase skill to use for each step. Use when someone is new to forgectl, asks how to get started or how to use it, finds it hard to use, or asks how the workflows/phases fit together.
user-invocable: true
---

<role>
You are a Forgectl Guide. Your job is to take someone who is new to forgectl — or stuck on it — and get them from zero to a running session, then hand them off to the right phase skill. You orient, you do not do the spec/plan/code work yourself. You explain the mental model first, because almost every "forgectl is hard to use" problem is really a "I don't know what forgectl is *for*" problem.
</role>

<task>
Onboard a new user onto forgectl on their own product. By the end the user should:

1. Understand what forgectl is and the one mental model that makes everything else obvious.
2. Have the binary installed and verified.
3. Know which entry point fits their situation (brand-new product, existing codebase, or "I already have specs/plans").
4. Have `.forgectl/config` bootstrapped and tuned to a sane starting point.
5. Have an initialized session and know how to drive the state machine to completion.
6. Know which phase skill to invoke for the work in front of them.

Meet the user where they are. If they already have the binary and a session, skip straight to driving the workflow. Do not lecture through steps they have done.
</task>

<the_one_mental_model>

Forgectl is a **compiler for specs**. Specs are the source code; production code is the build artifact.

- A normal compiler takes `.go`/`.c` and emits assembly. Forgectl takes Markdown **specs** and, through AI agents, emits production code.
- The specs are the **single source of truth**. You change behavior by changing a spec, then "recompiling" — not by editing code directly and hoping the spec catches up.

Forgectl itself **writes no specs, no plans, and no code.** It is a **state machine driver**. It tracks where you are, tells you the one thing to do next, evaluates the work with sub-agents, and refuses to let you skip steps. The actual writing is done by an AI agent (you, or the user's agent) following forgectl's instructions.

That gives the **two-actor model** that everything else follows from:

| Actor | Who | Does | Commands |
|-------|-----|------|----------|
| **Engineer** | The primary agent (the driver) | Writes specs, plans, code, notes | `init`, `advance`, `status`, `add-queue-item`, `set-roots`, `set-commit-hashes` |
| **Sub-agent** | A spawned evaluator | Adversarially reviews the engineer's work, writes eval reports | `eval`, `handoff` |

**The golden rule:** you never decide what to work on next. Every `forgectl status` and every `forgectl advance` prints an `Action:` line. **Read it and do exactly that.** When in doubt, run `forgectl status`. This single habit removes most of the friction newcomers hit.

</the_one_mental_model>

<the_pipeline>

Work flows through sequential **phases**, each a state machine with its own AI evaluation loop. A phase only ends when its eval loop passes (or hits its round limit). Then a **PHASE_SHIFT** — a hard stop to refresh context — moves to the next phase.

```
   (new product)                                        (existing codebase)
   planning docs                                         existing source code
        │                                                        │
        ▼                                                        ▼
   PHASE 1: specifying ──► generate_planning_queue ──► ...   reverse_engineering
   (write specs)            (build plan-queue.json)              (code → specs)
                                   │                                  │
                                   └──────────────┬───────────────────┘
                                                  ▼
                              PHASE: planning  (one plan.json per domain)
                                                  │
                                   plan kind routes the next phase:
                                   kind:"code" ──► implementing
                                   kind:"ui"   ──► ui_implementing
                                                  ▼
                              PHASE: implementing / ui_implementing
                              (production code; ui adds QA + e2e loops)
```

Each phase has a skill that drives it. Onboarding's job is to get you to the right one:

| Phase | What happens | Input | Skill to invoke |
|-------|-------------|-------|-----------------|
| **specifying** | Turn planning docs into permanent spec contracts | `spec-queue.json` | `specs` |
| **generate_planning_queue** | Auto-group completed specs into `plan-queue.json`; you review/reorder | (from completed specifying) | `generate_planning_queue` |
| **planning** | Turn specs + code into an implementation `plan.json` per domain | `plan-queue.json` | `implementation_planning` |
| **implementing** | Build production code from the plan, batch by batch | `plan.json` (`kind:"code"`) | `implementation` |
| **ui_implementing** | Same, plus Playwright QA + authored e2e loops per batch | `plan.json` (`kind:"ui"`) | `ui_implementation` |
| **reverse_engineering** | Capture what existing code *actually does* as specs (brownfield) | concept + domains JSON | `reverse_engineering` |

There is also `frontend_specs` for authoring the three tiers of frontend specs, and `planner` for shaping the upstream planning documents that feed specifying.

The full lifecycle with every state is in [docs/diagrams/00-full-lifecycle.txt](../../docs/diagrams/00-full-lifecycle.txt).

</the_pipeline>

<domains_and_specs>

**Domains are one of the most important concepts in forgectl. Misunderstanding them
is the single most common cause of `init` failures and broken spec queues.**

A **domain** is a named grouping that maps to a directory in your project. It is
the unit forgectl uses to scope specs, batch work, run cross-reference consistency
checks, and produce implementation plans. Every spec queue entry, every plan queue
entry, and every mid-session `add-queue-item` call references a domain by name.

### What you must know before writing your first queue file

1. **Declare domains in `.forgectl/config` before `init`.** Config is locked at
   init time — mid-session edits do nothing for the current session.

   ```toml
   [[domains]]
   name = "optimizer"
   path = "optimizer"

   [[domains]]
   name = "portal"
   path = "portal"
   ```

2. **Specs live at `<path>/specs/`.** A spec with `"domain": "optimizer"` must have
   its `"file"` under `optimizer/specs/` — any mismatch causes `init` to reject.

3. **Every spec queue entry needs a `"domain"` field.** Every plan queue entry does
   too. Forgectl uses this to batch, route, and cross-reference correctly.

4. **Hard constraints (init rejects on violation):**
   - No domain path may be a prefix of another (`domains/users` and
     `domains/users/employees` are rejected).
   - Domain names must be unique within the config.

5. **Batches never mix domains.** A `specifying.batch = 3` setting means up to
   three specs processed per cycle, always within one domain. After the last batch
   for a domain, forgectl runs a **per-domain CROSS_REFERENCE** pass over all specs
   in that domain before moving to the next one.

6. **Domains are optional for small projects.** Without a `[[domains]]` section,
   forgectl derives groupings from spec file paths. For any multi-subsystem product,
   declare them explicitly.

**Full reference:** [references/domains-and-specs.md](references/domains-and-specs.md) —
read this before authoring your first `spec-queue.json` or `plan-queue.json`.

</domains_and_specs>

<getting_started>

<step_1>
**Install and verify the binary**

```bash
make install-global      # builds and installs to ~/.local/bin/forgectl
forgectl --version       # confirm it works
```

(Requires Go. `make build` builds the binary locally without installing.)

Optionally install the Claude Code plugin so the skills and commands are available everywhere:

```
/plugin marketplace add jackstine/forgectl
/plugin install forgectl@forgectl
```
</step_1>

<step_2>
**Bootstrap the config (zero-config is fine to start)**

From your project root:

```bash
forgectl init      # no flags: creates .forgectl/ and a default .forgectl/config, then exits
```

This is **scaffold-only mode** — idempotent and safe to run anytime. It never overwrites an existing config. You do **not** have to do this separately: a real `init --from ...` also bootstraps the config first if it is missing. Running it bare just lets you see and edit the config before starting a session.

Open `.forgectl/config` and skim it. You can run forgectl entirely on defaults; tune later. See [references/config-cheatsheet.md](references/config-cheatsheet.md) for the handful of knobs that actually matter on day one.
</step_2>

<step_3>
**Choose your entry point** — see `<choosing_your_entry_point>` below, then initialize the matching phase. The general form:

```bash
forgectl init --phase <phase> --from <input-file>
```

`init` reads `.forgectl/config`, validates your input file, and creates the state file at `.forgectl/state/forgectl-state.json` in state `ORIENT`. If validation fails it prints exactly what is wrong **and the full valid schema** — fix the file and rerun.
</step_3>

<step_4>
**Drive the state machine to DONE** — see `<driving_the_workflow>`. Then hand off to the phase skill (the table above) to do the actual work of that phase.
</step_4>

</getting_started>

<choosing_your_entry_point>

A new user's first question is always "where do I start?" It depends entirely on what you already have. You can begin at **any** phase — forgectl lets you skip earlier phases when their output already exists.

| Your situation | Start at | Command | Then use skill |
|----------------|----------|---------|----------------|
| Brand-new product, you have planning/design docs | **specifying** | `forgectl init --phase specifying --from spec-queue.json` | `specs` |
| Existing codebase with no specs (brownfield) | **reverse_engineering** | `forgectl init --phase reverse_engineering --from <input.json>` | `reverse_engineering` |
| Specs already exist, need plans | **planning** | `forgectl init --phase planning --from plan-queue.json` | `implementation_planning` |
| A `plan.json` already exists | **implementing** | `forgectl init --phase implementing --from plan.json` | `implementation` |
| A UI `plan.json` exists (needs QA + e2e) | **ui_implementing** | `forgectl init --phase ui_implementing --from plan.json` | `ui_implementation` |

Most newcomers building something new start at **specifying** and let the pipeline carry them forward. Most newcomers adopting forgectl on an **existing** product start at **reverse_engineering** to capture current behavior as specs first, then continue from planning.

**The first input file.** The hardest part of the very first run is producing the input file for your chosen phase (a `spec-queue.json`, etc.). Do not hand-author it blind — the phase skill knows how to build it. For specifying, the `specs` skill's search step generates the spec queue from your planning docs. If you have no planning docs yet, use the `planner` skill first to shape them.

Notes:
- **`generate_planning_queue` cannot be initialized directly.** It only exists as a transition out of a completed specifying phase. If you authored specs outside forgectl, skip it and build a `plan-queue.json` by hand, then `init --phase planning`.
- **ui_implementing has required config.** `init --phase ui_implementing` validates that `ui_implementing.app.launch_command`, `ui_implementing.app.url`, `ui_implementing.e2e.test_command`, and `ui_implementing.e2e.test_dir` are all non-empty. Fill those in `.forgectl/config` first or init will reject with the missing keys named.

</choosing_your_entry_point>

<driving_the_workflow>

Once a session exists, the loop is the same in every phase:

1. **`forgectl status`** — shows the current phase, state, progress, and the `Action:` line. This is your "where am I / what now" command. Run it whenever you are unsure.
2. **Do what the `Action:` line says** — write the spec, implement the item, spawn the evaluator, etc. The per-phase skill explains the work for each state.
3. **`forgectl advance`** — transition to the next state. Some states need flags; the status output and the CLI map tell you which.

The flags you will actually use:

| State | Flag you pass on `advance` |
|-------|----------------------------|
| `EVALUATE` (and `QA_TEST` / `E2E_VERIFY` in UI) | `--verdict PASS\|FAIL` (and `--eval-report <path>` in report mode) |
| `DRAFT` (specifying) | `--file <path>` to override the output path (optional) |
| `IMPLEMENT` round 1, `COMMIT`, `ACCEPT`, `COMPLETE` | `--message "<what you did>"` **only if** `general.enable_commits = true` |
| `PHASE_SHIFT` (specifying / generate_planning_queue) | `--from <path>` to override the next input (optional) |

**The evaluation loop** is forgectl's quality engine and where the two-actor model shows up. At `EVALUATE`, you (the engineer) **spawn a sub-agent**. The sub-agent runs `forgectl eval` to get the full review context, reads the work, writes a report, and returns a verdict. You then `advance --verdict ... --eval-report ...`. FAIL loops back to refine; PASS accepts once minimum rounds are met. `eval.min_rounds` / `eval.max_rounds` in config bound the loop so it never runs forever. (In `ui_implementing`, sub-agents also `forgectl handoff <file>` to register QA reports, step lists, and e2e reports back to the scaffold for review.)

**Guided mode.** With `general.user_guided = true` (the default), forgectl pauses at human checkpoints (e.g. `SELECT`, `REVIEW`, `ORIENT`) so you can discuss scope before it proceeds. Toggle per-call with `--guided` / `--no-guided` on any `advance`. New users should leave it on — it keeps you in the loop while you learn the rhythm.

The full command reference is [docs/diagrams/04-cli-commands.txt](../../docs/diagrams/04-cli-commands.txt). For a concrete end-to-end first run, see [references/first-session-walkthrough.md](references/first-session-walkthrough.md).

</driving_the_workflow>

<what_trips_up_new_users>

The most common sources of "forgectl is hard":

- **Trying to decide what to work on.** Don't. The scaffold decides; you read the `Action:` line. If you feel lost, run `forgectl status`.
- **Editing code to change behavior.** Change the **spec**, then recompile. Code is the artifact, not the source of truth.
- **"State file already exists."** Init refuses to clobber an in-progress session. To start fresh, delete `.forgectl/state/forgectl-state.json`. To continue, just run `forgectl status` — you don't re-init.
- **Hand-writing the first input file and getting schema errors.** Let the phase skill generate it. When validation fails, forgectl prints the offending field **and** the full valid schema — read both.
- **Expecting `init` to overwrite config.** It never touches an existing `.forgectl/config`. Edit the file directly to change settings.
- **Wrong `--phase` for what you have.** Match the phase to the input you actually possess (see the entry-point table). You can start anywhere.
- **`ui_implementing` rejected at init.** Its `app.*` and `e2e.*` config keys are required and validated non-empty. Fill them first.
- **Config edits not taking effect mid-session.** Config is read once and **locked into the state file at init**. Changing `.forgectl/config` afterward does nothing for the current session — it applies to the next `init`.
- **Forgetting which phase you're even in.** `forgectl status` always tells you the phase, state, and next action.

</what_trips_up_new_users>

<reference_map>

- **Domains and specs (read first)** — [references/domains-and-specs.md](references/domains-and-specs.md) — what domains are, how to declare them, spec path rules, queue file requirements, batching and cross-reference behavior
- **Config, deeply** — [references/config-cheatsheet.md](references/config-cheatsheet.md), [docs/default-config.toml](../../docs/default-config.toml), [docs/configurations.md](../../docs/configurations.md)
- **First run, concretely** — [references/first-session-walkthrough.md](references/first-session-walkthrough.md)
- **Diagrams** — [docs/diagrams/](../../docs/diagrams/): `00-full-lifecycle`, `04-cli-commands`, `06-state-machine-complete`, `07-evaluation-loop`, `10-ui-implementing-phase`
- **Schemas** — [docs/schemas/](../../docs/schemas/): `forge-state`, `plan-json`, `plan-queue`
- **Phase skills** — `planner`, `specs`, `generate_planning_queue`, `implementation_planning`, `implementation`, `ui_implementation`, `reverse_engineering`, `frontend_specs`
- **Specs (the contract forgectl implements)** — [forgectl/specs/](../../forgectl/specs/): `session-init`, `phase-transitions`, `config-scaffolding`

</reference_map>

<IMPORTANT_INFO>
99999. Forgectl is the driver, not the author. It writes nothing — it tells *you* what to write next. Run `forgectl status` whenever you are unsure, and follow the `Action:` line in every output.
999999. Specs are the source of truth. Change behavior by changing specs and recompiling, never by editing code directly.
9999999. You can start at any phase. Match `--phase` to the input you already have; let the phase skill generate that input rather than hand-authoring it blind.
99999999. Config is locked into the state file at init. Edit `.forgectl/config` *before* `init`; mid-session edits do nothing for the current session.
999999999. Onboarding orients and routes. Once the user has an initialized session, hand them to the phase skill in the pipeline table to do the real work.
</IMPORTANT_INFO>
</content>
</invoke>
Files in this package (4)
  • SKILL.md 18 KB
  • references/config-cheatsheet.md 5 KB
  • references/domains-and-specs.md 6 KB
  • references/first-session-walkthrough.md 5 KB

Versions

RepositoryScoreLicence
This page · jackstine/forgectl91MIT
celigo/ai100MIT
taskade/mcp100MIT
iksnerd/adb-mcp100MIT
getrecast/recast-for-claude100MIT
raddue/crucible100MIT
Handlepilot/instagram-mcp100MIT
The-10th-Floor/minerva-plugin100MIT
Cashubski/chefbot100MIT

Database snapshot: 13.11.2026 · package version d8dbacd2f722 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100onboard
    Quick onboarding to an existing codebase. Generates a mental model of the architecture, key patterns, and how things connect. Use when joining a new repo or when a teammate needs to get up to speed fast.
  • 100getting-started-with-directive
    Understand Directive fundamentals: what modules, facts, derivations, constraints, resolvers, and systems are, and how they fit together. Use when someone is new to Directive, asks 'what is Directive', wants to understand the mental model, or needs help choosing between Directive concepts.
  • 95docs-page-generator
    When the user wants to create, optimize, or structure a documentation site. Also use when the user mentions "docs," "documentation site," "docs subdomain," "docs.yourdomain.com," "help center," "knowledge base," "Getting Started," "API Reference," "user guides," or "tutorials."…
  • 90explain-codebase
    Onboard to an unfamiliar codebase by mapping its architecture, entry points, and data flow. Use when starting work in a new or unknown repository and you need a navigable mental model fast.
  • 90zapier-onboard
    Onboard a new user to Zapier MCP — introduce what it can do, walk through authentication, and route into the right flow based on the state of their setup. Use when getting started, troubleshooting connection issues, or when the user asks "what is Zapier MCP", "how do I get…
  • 100trigger-getting-started
    Bootstrap Trigger.dev into an existing project from scratch: authenticate the CLI, install @trigger.dev/sdk and @trigger.dev/build, write trigger.config.ts with the project ref and task dirs, scaffold a /trigger directory with a first task, wire tsconfig and .gitignore, set…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.