Skip to content

First Project Walkthrough

The quickstart gets gald3r installed and confirms the plumbing works. This page goes one step further: a complete walkthrough of scaffolding a brand-new project, tracking real work in it, and taking a task from creation through to completed. Every command and every block of output below was run against a real, throwaway scratch project while writing this page — nothing is invented.

1. Scaffold a new project

From an empty directory:

gald3r setup --dry-run

Would scaffold .gald3r/ at <path>
  [would create    ] dir  .gald3r
  [would create    ] dir  .gald3r/project
  [would create    ] dir  .gald3r/project/tasks
  [would create    ] dir  .gald3r/project/tasks/cancelled
  ...
  [would create    ] file .gald3r/project/TASKS.md
  [would create    ] file .gald3r/project/BUGS.md
  [would create    ] file .gald3r/CONSTRAINTS.md
  ...
  [would create    ] file .gitignore

44 item(s) would be created; 0 already exist (dry run -- nothing written).

--dry-run writes nothing — it's the safe way to see exactly what setup is about to do before committing. Drop the flag to actually create it:

gald3r setup

  [created         ] file .gald3r/linking/INBOX.md
  [created         ] file .gitignore

44 item(s) created; 0 already existed (skipped).

No IDE overlay installed -- .gald3r/ only. Run 'gald3r platform install <platform> --into .' to
wire commands/rules/skills/hooks for your IDE, or pass --platform <name> to this command next
time.

setup is idempotent — re-running it on an already-scaffolded project only fills in what's missing, never overwrites what's there. A fresh project gets the current v2 layout, which nests the SDLC artifacts under .gald3r/project/ — run gald3r layout show any time to print the resolved path for every artifact (TASKS.md, tasks/, PLAN.md, and the rest).

2. Confirm the new project is healthy

gald3r doctor

doctor runs identity, overlay, path-resolution, platform-parity, hooks, and local-database consistency checks in one pass, and never fabricates a green result — see Quickstart → step 2 for what each check covers. On a project this fresh (no IDE overlay installed yet), most rows report skip rather than fail — that's expected, not a problem to chase down.

3. Create real work

gald3r task add "Write the landing page copy" -d "Draft hero + feature sections" --type feature --priority high
gald3r task add "Fix broken footer link" -d "404 on /pricing" --type bug_fix --priority medium

Created task 1: Write the landing page copy
Created task 2: Fix broken footer link

gald3r task list

1        v8  high       pending    Write the landing page copy
2        v5  medium     pending    Fix broken footer link

4. Work a task through its full lifecycle

gald3r task update T1 --status in-progress

Task T1 -> in-progress

gald3r task update T1 --status awaiting-verification

Task T1 -> awaiting-verification

gald3r task verify T1 --pass

Task T1 verified: PASS

5. Check where the project stands

gald3r status

gald3r status -- <path>
=============================================================

Tasks (2 total, 50.0% complete)
  pending    1
  completed  1

Pending breakdown: runnable 1, gated 0, blocked 0, below-value-floor 0

Bugs (0 open, 0 all statuses)
  (none)

Awaiting verification (0)

Dependency-blocked pending tasks (0)

Active milestone: (none)
WPAC: not configured / skipped (link_topology.md absent)

Notice WPAC: not configured / skipped — a brand-new standalone project has no cross-project links yet, which is a completely normal state (see coordination.md for when/how to set that up).

6. Try the agent plumbing, offline

gald3r run "hello gald3r" --backend dev-echo

[echo #0] r3dlag olleh

--backend dev-echo is a deterministic, offline stand-in — no API key, no network call. It proves the run pipeline works end to end before you configure a real provider with gald3r init-providers.

7. See what gald3r would work on next, without doing it

gald3r db backfill
gald3r task next

T2: Fix broken footer link
Status: pending
Priority: medium

task next is read-only — it never claims or mutates anything. With T1 now completed above, T2 is the only pending task left, so it's what comes back. See autopilot.md for what gald3r go actually does once you run it for real, and for letting gald3r work through several tasks unattended.

Where next