Improve non-coder onboarding

[samtay32]

What changed

• add an explicit safety-boundary statement to the README, operating manual, and installed agent contract
• add doctor --human with plain-language ready, almost-ready, and safety-repair guidance while preserving JSON as the default contract
• add configure --preset simple for approved standard, built-in-review, repository-knowledge, local-only, human-merge defaults
• reject attempts to mix the preset with manual configuration overrides
• strengthen the README's 30-second non-coder path and update installed setup guidance

Why

The package's mechanical guardrails are strong, but the first-run experience still required non-technical users to interpret structured output and technical configuration choices. This change simplifies that welcome path without weakening the underlying installation or changing the agent-facing JSON interface.

User impact

A non-coder can ask an agent to recommend the simple setup and can run doctor --human to receive one concrete next action. Production or external-provider projects continue through the existing advanced configuration flow.

Verification

• npm run release:check
• 64/64 tests passed
• packed-install smoke test passed with 77 intended files
• Markdown lint passed for all changed documentation
• setup-autonomous-project skill validation passed
• git diff --check passed

Summary by CodeRabbit

• New Features

  • Added a simple configuration preset for local or straightforward projects.
  • Added doctor --human for plain-language readiness guidance with a next action.
  • Preserved JSON output as the default for automated workflows.

• Documentation

  • Clarified onboarding paths, safety boundaries, and when to use the simple preset.
  • Added guidance emphasizing that package controls do not replace sandboxing, permissions, backups, or human oversight.

• Bug Fixes

  • Improved setup guidance for selecting appropriate configuration based on project requirements.

[coderabbitai]

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3a7fb303-810f-4521-9463-42d72ae87e50

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Walkthrough

The CLI adds a simple configuration preset and a doctor --human output mode while retaining JSON by default. Documentation and onboarding workflows describe preset selection, safety boundaries, and advanced configuration conditions. Tests cover preset validation, persisted settings, doctor output, and protected-file failures.

Changes

CLI onboarding behavior

Layer / File(s)	Summary
Simple preset configuration bin/ultimate-agent-stack.mjs, test/agent-stack.test.mjs	Adds validated simple defaults, preset-aware configuration wiring, response reporting, help text, and persistence tests.
Human-readable doctor output bin/ultimate-agent-stack.mjs, test/agent-stack.test.mjs	Adds doctor --human formatting and emission while preserving JSON output by default; tests cover pending, ready, and protected-file states.
Onboarding and safety guidance README.md, assets/project-template/*, docs/OPERATING_MANUAL.md, skills/setup-autonomous-project/SKILL.md	Documents the simple-project path, safety boundaries, doctor workflow, and conditions requiring advanced configuration.
Release documentation CHANGELOG.md	Records the new CLI behaviors and setup guidance changes.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant DoctorReport
  participant formatDoctorHuman
  participant Output
  CLI->>DoctorReport: run doctor checks
  DoctorReport-->>CLI: return readiness result
  CLI->>formatDoctorHuman: format result when --human is set
  formatDoctorHuman-->>CLI: return plain-language summary
  CLI->>Output: emit summary or default JSON

Loading

Possibly related PRs

• samtay32/ultimate-agent-stack#7: Both modify the CLI doctor reporting path.
• samtay32/ultimate-agent-stack#9: Both modify guided CLI onboarding and configuration flows.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: onboarding improvements for non-technical users.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/improve-noncoder-onboarding

---

_{Comment @coderabbitai help to get the list of available commands.}

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@bin/ultimate-agent-stack.mjs`:
- Around line 2103-2197: Refactor the status-selection logic in
formatDoctorHuman into a priority-ordered, data-driven table of entries
containing each predicate and its status, explanation, and nextAction, then
select the first matching entry. Preserve the current branch precedence and
exact messages, including the result.ok default and all failure-specific
conditions, while leaving failure and warning list rendering unchanged.
- Around line 1666-1674: Update resolveConfigureOptions to validate preset names
with an own-property check before using CONFIGURATION_PRESETS[preset]. Reject
inherited names such as constructor, toString, hasOwnProperty, and valueOf with
the existing StackError listing valid presets, while preserving normal preset
resolution and downstream reviewer handling.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e22adfa7-b56c-4fdc-8189-cf3b1298e270

📥 Commits

Reviewing files that changed from the base of the PR and between 9869d7a and 2c96e38.

📒 Files selected for processing (8)

• CHANGELOG.md
• README.md
• assets/project-template/.agent-stack/HANDOFF.md
• assets/project-template/AGENTS.md
• bin/ultimate-agent-stack.mjs
• docs/OPERATING_MANUAL.md
• skills/setup-autonomous-project/SKILL.md
• test/agent-stack.test.mjs

[samtay32]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.