Configure A New Project

How to configure a new project on first session

Note

Goal: Open a repo the harness hasn't seen, run the detection flow, and persist an approved enablement config so every later phase resolves this repo's {slug, type, enabled skills/hooks}. Prereqs: agentm v4.8.0+ (ships V4 #32), python3 on PATH, and a repo with a .git dir. A reachable vault (MEMORY_VAULT_PATH) to persist the config — without one the proposal still renders but the write is skipped.

When you open an unconfigured code project, the SessionStart hook emits a one-line nudge offering to configure it. Saying "configure this project" or running /setup --detect scans the repo, renders a default-all-enabled proposal with a per-skill/per-hook rationale, and writes the approved enablement block to project.json on approval.

Steps

1. Open the unconfigured repo. The harness-context-session-start hook fires a single line each session until the repo is registered or .agentm-no-register is present:

   [agentm] New project — I haven't configured this repo. Say 'configure this project' or run /setup --detect.
   

2. Run the detection flow. Say "configure this project" or run /setup --detect. /setup runs detection as its first step (§0), before the inventory + interview:

   python3 scripts/detect_project.py . --format json   # structured proposal (drives agent logic)
   python3 scripts/detect_project.py . --format text   # operator-facing approval block

3. Read the proposed config block. Every enableable skill and hook starts enabled (✓); each line carries a rationale — a default reason, or a detection reason when a rule matched this repo. See Detection rules for the 10 rules and what each attaches a rationale to.

4. Choose a/b/c:

   • (a) Register with all-enabled — python3 scripts/project_config.py register .
   • (b) Register with custom selection — answer per-skill/per-hook (Enter keeps the default of enabled), then pass each decline: python3 scripts/project_config.py register . --disable <name> --disable <name>. Each --disable records an operator_overrides entry.
   • (c) Skip — touch .agentm-no-register. One-time scratch session; the nudge stays silent until you remove the marker.

5. On (a) or (b), finish registration. register writes the enablement block to project.json (see Project config) and registers the repo in the vault repo_registry. Then:

   • Create the vault _index.md at <vault>/projects/<slug>/_index.md if absent — confirm the project dir with python3 scripts/harness_memory.py vault-state-path PLAN.md.
   • Accept or decline the offer to add a vault_slug: <slug> line to AGENTS.md (operator-confirmed; never silent).

6. Re-open the repo. python3 scripts/project_config.py is-registered . prints registered (exit 0) and the SessionStart nudge stays silent.

Related

• Detection rules reference — the 10 built-in rules and what each detects.
• Project config reference — the project.json enablement-block schema this flow writes.
• Auto-detect + auto-configure — why the flow proposes-then-approves and why config lives in project.json.
• Install into project — the install step that precedes first-session configuration.