Set up your first project

Use this guide after Jentrix is running and the jentrix CLI is authenticated. It gives a coding agent one prompt to inspect a repository, propose a sensible Jentrix structure, and—after you approve the proposal—create the first board, project, and anchor task.

Run the prompt from the repository root in a coding agent that can read the working tree and run shell commands. The agent does not need direct MCP configuration: it uses the jentrix CLI you already installed.

Claude Code users get the session commands (/jentrix-connect, /jentrix-align, /jentrix-plan) with jentrix plugin install. A broader operator skill pack ships in the source checkout at skills/stacks-templates/ (a separate nested repo, not part of the published repository): its stacks-workspace-designer skill builds the approved board topology inside the selected workspace. The prompt below remains the canonical end-to-end repository analysis and project/task bootstrap workflow.

The first-project shape

For most software repositories, start with this small structure:

Workspace                         existing team boundary
├─ TASKS board                    day-to-day delivery flow
│  └─ Anchor task                 the first governed unit of work
└─ Project                        goal, constraints, risks, and metrics

That is the whole shape for most repositories. A full deployment can add a governed spec → plan → reviewed-stages → commits harness on top; the extension clauses for that live in Harness automation → Bootstrapping a project with a harness.

Do not create one workspace per repository by default. A workspace is the team, membership, and security boundary; projects and boards organize repositories inside it. Create a separate workspace only when the people or access boundary is genuinely different.

Know the bootstrap boundary

Not every setup operation is available through MCP or the CLI. This is intentional: identity and credential bootstrap stays human-controlled.

Before you paste the prompt

1. Create or select the workspace in the app.

2. Install and authenticate the CLI from Setup in the app (workspace nav → Setup). It renders the install command resolved for this deployment, with nothing to fill in, and reports what the server has observed at each step — including the two local checks (jentrix --version, jentrix whoami) for the one fact a server can never see, whether this machine has the toolchain. Do not assemble an install sequence from this page.

3. jentrix login (what Setup runs) gets read + write, which is all this prompt needs. A headless checkout that cannot open a consent screen uses a PAT pinned to the target workspace instead — and note that scopes are not hierarchical, so a PAT needs each one it uses listed explicitly. Creating a project additionally requires the human behind the credential to be a workspace admin.

4. Commit or stash unrelated local changes if you want the repository analysis to describe a clean baseline. The onboarding prompt itself tells the agent not to edit the repository.

Copy/paste onboarding prompt

This prompt is the deep-analysis path, not the way in. It exists for bootstrapping a whole repository topology — board, project, anchor task — in one agent turn, and it is the one place in the product that still asks you to fill anything in. To start working, use Setup instead: it hands you every command with nothing to fill in and reports each step from durable rows. Come back here when you want the full topology proposed for you.

Replace the bracketed hints if you know them. Leaving a hint as auto tells the agent to infer it, but the agent must stop when a choice is ambiguous.

You are onboarding the repository in the current working directory into Jentrix.

Hints:
- Target workspace name or slug: [auto]
- Project name: [auto — infer from the repository]
- Accountable human owner: [auto — ask if more than one member is plausible]

Your job is to analyze first, propose the Jentrix topology, wait for my approval,
and only then create it with the installed `jentrix` CLI.

Operating rules:
1. Do not edit application code, configuration, git state, or remote services.
   This task may read the repository and may create approved records in Jentrix.
2. Never read or print secrets. Do not inspect `.env` files, credential stores,
   or token values. Files such as `.env.example` are safe when they contain
   placeholders only. Never put a secret in a Jentrix task, project, comment,
   artifact, or command output.
3. Use `jentrix --help` and command-level `--help` as the source of truth. Do not
   invent commands or flags. Use `jentrix tool <tool_name> --args ... --json` as
   the fallback when a generated noun/verb command is unclear.
4. Use `--json` for every Jentrix read and parse the returned ids; do not scrape
   human-formatted tables. Prefer concise response formats where supported.
5. Read before writing and follow `nextCursor` until paginated discovery is
   complete. Reuse a clearly matching existing workspace, board, project, or
   task instead of creating a duplicate. Never reuse an idempotency key
   across different tools or different arguments.
6. The CLI cannot create a workspace or register/credential an agent profile.
   Do not bypass that boundary with database access or an undocumented API.
   Report the required UI step instead.
7. Treat FORBIDDEN as a scope/role/workspace-pinning problem. Treat CONFLICT as
   a signal to re-read current state before deciding. Do not work around either.

Phase 1 — read-only discovery and repository analysis:

A. Verify that this is a git repository. Inspect only the files needed to
   understand it: README and docs, package/build manifests and lockfiles,
   workspace configuration, CI workflows, deployment configuration, test/lint
   configuration, and the top-level source layout. Inspect git remotes and the
   default branch without fetching, pulling, or contacting a remote.
B. Summarize:
   - the product's purpose and users;
   - the architecture, major components, and deployment shape;
   - the verified install, development, build, test, lint, and typecheck commands;
   - current roadmap signals, risks, missing documentation, and likely first
     milestones;
   - a concise project goal, constraints, and 3–5 measurable success metrics.
   Clearly label facts from the repository separately from your inferences.
C. Run `jentrix --version` and `jentrix whoami --json`, then discover the accessible
   workspaces. Resolve the workspace hint. If none exists, or more than one
   matches, stop and ask me to create or choose one in the Jentrix app.
D. In the chosen workspace, read members, boards and columns, and projects.
   Identify the human owner.
   If owner selection is ambiguous, ask me—`create_project` requires a member id.
E. Propose the smallest useful topology:
   - reuse a suitable delivery board, otherwise create one TASKS board;
   - one project for this repository, with the inferred goal and constraints;
   - one anchor task in the board's chosen intake/backlog column describing the
     first concrete outcome, not a vague “set up project” placeholder.
F. Show a compact plan with every object you would create or reuse, its name,
   rationale, important settings, and any missing prerequisite. Also list what
   must still be linked or edited in the UI. If authoring may start, include the
   exact proposed authoring objective. Do not mutate Jentrix yet.
G. End with exactly: “Reply `Proceed with the Jentrix bootstrap` to create this
   topology, or tell me what to change.” Then stop.

Phase 2 — only after I provide that exact approval:

H. Re-read the chosen workspace to avoid duplicates or stale ids. Create only
   the approved missing objects. Use a distinct, stable idempotency key for each
   create call. Resolve the target board's actual intake/backlog column id before
   creating the task; if a reused board has more than one plausible column, ask
   rather than guessing.
I. Create the project with the confirmed human owner, goal, constraints, and
   success metrics. Do not claim that board/task/repo links were added if the
   tool surface cannot add them; put those in the UI follow-up list.
J. Validate the result with fresh Jentrix reads. Report:
   - created versus reused records, with ids, keys, slugs, and names;
   - every skipped action and why;
   - the short UI checklist for project links;
   - the exact safest next command or prompt, without executing it.

What the prompt deliberately does

The approval pause prevents a repository name or an ambiguous workspace from turning into permanent duplicate records. Stable idempotency keys make a lost response safe to retry, while the second read before writes catches anything that changed while you reviewed the proposal.

Nothing here runs an agent against your repository: the prompt reads the working tree and writes Jentrix records, and that is the whole blast radius. Governed execution is a separate, explicit step on a full deployment.

Finish the UI-only links

After the CLI bootstrap, open the new project and complete Settings → Linked items:

• link the delivery board and anchor task;
• add the repository reference and any source/design documents;
• review milestones, risks, and success metrics inferred from the repository.

Next

Run your first recorded session against the anchor task — see Your first session. On a full deployment you can also put the project under a governed harness; the extension clauses for the prompt above are in Harness automation.