feat: add auto onboarding support

[pascalandr]

Summary

• Adds automatic NomadWorks repository onboarding for Git repositories.
• Adds plugin options for onboarding mode, default team mode, and Git-repo-only auto-init safety.
• Refactors initialization scaffolding so manual nomadworks_init and auto-onboarding share the same repository scaffold path.
• Includes tuple-style OpenCode plugin option support and scaffold YAML insertion hardening needed for reliable real-world config loading.

Why

This PR makes NomadWorks easier to use immediately after installation: open a Git repo, let NomadWorks create the expected workflow scaffolding, and avoid manual initialization drift. It is scoped to repository onboarding only; long-term memory/PAI sync is handled separately.

Review notes

• Independent PR targeting dev.
• Excludes PAI/session sync tools and context injection.
• Includes .gitignore coverage for .nomadworks/ runtime/generated state.

Verification

• Branch verification: npm test — PASS, 11 tests.

[pascalandr]

@CodeNomadBot

I want you to perform the gatekeeper checks for latest PR state

check for regressions
check for better possible implementations
Be the PR gatekeeper
Be ruthless about code quality

[codenomadbot]

Gatekeeper review for latest PR state.

Understood request: perform a strict PR quality/regression review of PR #4, not make code changes. Assumption: this is a review-only pass unless a blocking issue requires follow-up changes by the PR author.

Gatekeeper Result

Request changes.

Findings

1. Blocking: .gitignore now ignores the entire .nomadworks/ tree.

   Reference: .gitignore:5

   This conflicts with the product model documented throughout the repo: .nomadworks/nomadworks.yaml, .nomadworks/policies/, .nomadworks/agents/, and .nomadworks/agent-additions/ are repository-local configuration/customization surfaces that users are expected to keep with the repository. Ignoring the whole directory will hide those files from Git, making auto-onboarding/manual init appear to work locally while preventing the important config from being committed. That is exactly the kind of silent onboarding regression this PR should not introduce.

   Better implementation: ignore only generated/runtime state, for example .nomadworks/runtime/, .nomadworks/generated/, or explicit generated artifacts. Do not ignore .nomadworks/nomadworks.yaml, repo policies, repo agents, or repo additions.

Quality Notes

• The shared scaffoldRepository() extraction is directionally good and reduces drift between manual init and auto-onboarding.
• The regex replacement for the agents: YAML insertion is safer than the prior broad string replacement.
• The new test covers the tuple-style second-argument options path, but it does not cover the negative/safety modes (onboarding: "off", non-Git worktree with default auto_init_git_repos_only, or existing config preservation). Add at least one safety-mode test before relying on auto-init behavior broadly.

Verification Run

• npm ci completed successfully, with existing audit warnings reported by npm: 2 moderate, 1 high.
• npm test passed: 2 suites, 11 tests.
• npm run build passed.
• npm pack --dry-run passed and rebuilt dist/ successfully.

I would not merge until the .gitignore rule is narrowed so repository-local NomadWorks configuration remains trackable.

--
Yours,
CodeNomadBot

[pascalandr]

@CodeNomadBot
same review

[codenomadbot]

Gatekeeper re-review for latest PR state.

Understood request: rerun the same strict PR gatekeeper review on the updated PR. Assumption: review-only pass, no code changes.

Gatekeeper Result

Request changes.

Findings

1. Blocking: .gitignore still ignores the entire .nomadworks/ directory.

   Reference: .gitignore:5

   This remains a merge blocker. .nomadworks/nomadworks.yaml, .nomadworks/policies/, .nomadworks/agents/, and .nomadworks/agent-additions/ are repository-local configuration/customization surfaces. Ignoring all of .nomadworks/ makes auto-onboarding/manual init create important config that users cannot see in git status and will not commit by default. That creates a silent failure mode where onboarding appears successful locally but the repository never actually receives the NomadWorks config.

   Better implementation: ignore only generated/runtime state, such as .nomadworks/runtime/ and .nomadworks/generated/, not the whole .nomadworks/ tree.

Updated Assessment

• The new commit improves option merging by preserving second-argument tuple options even when input.options is an empty object. That fixes the tuple-options issue I was concerned about.
• The new test covers that empty-input.options case and passes.
• I still want negative/safety coverage before calling this robust: onboarding: "off", non-Git worktree with default auto_init_git_repos_only, and existing config preservation. These are not as severe as the .gitignore blocker, but they are the high-risk edges for auto file creation.

Verification Run

• npm test passed: 2 suites, 12 tests.
• npm run build passed.
• npm pack --dry-run passed and rebuilt dist/ successfully.
• Working tree remained clean after verification.

I would not merge until the .gitignore rule is narrowed so repository-local NomadWorks configuration remains trackable.

--
Yours,
CodeNomadBot

[pascalandr]

@CodeNomadBot
same review

[codenomadbot]

Gatekeeper re-review for latest PR state.

Understood request: rerun the same strict PR gatekeeper review on the updated PR. Assumption: review-only pass, no code changes.

Gatekeeper Result

No blocking findings found in the latest state.

Updated Assessment

• The prior blocker is resolved: .gitignore now ignores only .nomadworks/runtime/ and .nomadworks/generated/, leaving repository-local .nomadworks/nomadworks.yaml, policies, agents, and agent additions trackable.
• The new safety tests cover the high-risk auto-onboarding edges I previously called out: onboarding: "off", non-Git worktrees with default git-only behavior, and existing config preservation.
• The code change to only scaffold NomadWorks README/generated policy support when config exists avoids creating .nomadworks/ as an incidental plugin-load side effect when onboarding is off or skipped. That is the right direction for auto-onboarding safety.
• The added repository codemap.yml files validate cleanly. They are broader than the narrow auto-onboarding feature, but they do not appear to introduce a functional regression.

Non-Blocking Notes

• suggest currently behaves the same as off from a filesystem perspective. The docs now state only auto scaffolds, so this is not misleading enough to block, but a future PR should either implement an actual suggestion path or avoid exposing suggest as a distinct mode.
• npm pack --dry-run includes agents/codemap.yml and policies/codemap.yml because those directories are package allowlisted, while root/source/test codemaps are not included. I do not see runtime impact because discovery filters markdown files, but keep that package-content asymmetry intentional.

Verification Run

• npm test passed: 2 suites, 15 tests.
• npm run build passed.
• npm pack --dry-run passed and rebuilt dist/ successfully.
• nomadworks_validate_logic(process.cwd()) passed with no errors or warnings.
• Working tree remained clean after verification.

I would allow this through from a gatekeeper perspective, subject to normal maintainer judgment on the non-blocking scope/package-content notes.

--
Yours,
CodeNomadBot