Skip to main content
Add a Project to group one product’s working repositories, Linear project, specification source, limits, and scheduled jobs.

​
Before you begin

Prepare a declared agent CLI and base route in Settings. Gather local repository paths and their verification commands, the intended Linear workspace/project, a GitHub connection, and the specification checkout. Acme Checkout below is an illustrative product name.

​
Define Project scope

Open Add Project…. If Before You Start appears, follow its Open Settings → Agent CLIs… link, declare a CLI and configure a base route, then return. In Project, enter a name such as Acme Checkout. Inspect the generated Project ID. Use Edit Id… before adding if you need another ID. The ID names the Project’s configuration, Journal, and three LaunchAgents and cannot be changed after adding; the display name can be changed later. In Board, connect or select the Linear workspace, choose your Operator identity, and select and verify an existing Linear project or choose a team for a new one. See Connect Linear.

​
Add repositories

In Repos, choose Add Repo… for each local checkout. Review each repository’s name and path, select its Repo Role, and enter its Check command. Use none only when you intend to declare no Check. The Suggestions menu supplies common commands, but you should choose one that actually verifies that repository. A working repository belongs to one Project. Resolve any displayed conflict before continuing. Do not add unrelated repositories merely because they share a parent folder. With two or more repositories, review Repo Dependencies. The scan shows evidence for proposed consumer/producer relationships. Set Read by and choose Confirm or Decline; Undo returns a proposal to pending. Only confirmed dependencies are written. A Feature does not change both ends of a declared dependency; consumers can wait for a producer’s merge or release.
Planned relationship diagram
What belongs to one Project

Show one product grouped with its repositories, Linear project, and specification.

Planned diagram: the Project links these inputs and the Night works within this scope.

​
Complete the remaining steps

  1. In Code Hosting, choose a Code Hosting Connection and inspect the per-repository access report.
  2. In Spec Source, choose A shared spec folder or A Repo in this Project. See Prepare your specification.
  3. Review Bounds. Keep the defaults initially or adjust the displayed per-Project limits.
  4. Open Schedule (the pane is titled Scheduled jobs), set the Night window and choose whether to install jobs, export them, or use Not now. Choose Not now if you want to review setup before enabling automatic runs.
  5. When all steps are ready, choose Add Project, confirm the permanent ID, and read the run log. Choose Done after success.

​
Confirm it worked

The Project appears in the sidebar. Open its Settings entry and confirm the Linear project, repositories, specification source, and connection match the intended product. Inspect any setup warnings before running a Night.

​
Common problems

  • The Add Project button is unavailable: inspect the step summaries and problem counts; each required step must be complete.
  • A repository belongs to another Project: correct the selected checkout or Project membership before proceeding.
  • Setup fails after you confirm: read the log. The Project file may already exist, so inspect Settings before attempting to add it again.
  • Chosen Bounds could not be saved: the run view reports that the Project was added with default Bounds. Change them in Settings → Recalibrate for that Project.

​
Next steps

Prepare your specification · Projects, Features, and Work Cards