Skip to content

feat: add first-run setup interview gate (PROTOCOL_RULES §P10)#22

Open
leonardobuares wants to merge 2 commits into
mmilanez:mainfrom
leonardobuares:feat/first-run-setup-interview
Open

feat: add first-run setup interview gate (PROTOCOL_RULES §P10)#22
leonardobuares wants to merge 2 commits into
mmilanez:mainfrom
leonardobuares:feat/first-run-setup-interview

Conversation

@leonardobuares

Copy link
Copy Markdown
Contributor

Summary

When a project still runs the pristine PROJECT_RULES.md template, agents currently proceed against an unconfigured scaffold (and a pristine §J8 even breaks the baseline boot, since step 3 loads the modules named there). This PR adds a protocol-level boot gate: any compliant agent, on any install path, runs a short setup interview on first boot and writes the project identity before serving requests. It is rules text only, no runtime code, so it works for copy-paste installs, the CLI, and every agent.

Closes #21.

Changes

  • .agents/PROTOCOL_RULES.md: new section §P10 First-run setup interview (pristine detection, framework-source carve-out, hard gate with one-time later defer, non-interactive skip, the interview table, AGENTS_MAP governance, self-clearing idempotency). Kernel version 2.0.1 to 2.1.0.
  • .agents/CORE_RULES.md: added a baseline-load note and an essential-contract subsection "First-run setup is a hard boot gate" pointing to §P10. Version 1.5.0 to 1.6.0; Protocol reference updated to v2.1.0.
  • .agents/modules/meta-repo.md: added a PROJECT_RULES.md row to the §M-meta-4 pristine-markers table, cross-referencing §P10. Version 1.1.0 to 1.1.1.
  • CLAUDE.md and AGENTS.md: added boot step 2a (Setup gate) that runs the interview when pristine and no .lead-protocol-source sentinel is present.
  • README.md: Current version 2.1.0; a "First run" note in the boot section; quick-start identity comment softened to note the agent will interview you; new 2.1.0 row in Version history.
  • .lead-protocol-source (new, repo root): sentinel that disables the gate in the framework's own source repo. It lives outside .agents/, so neither install path ships it to consumers.

Testing

  • python .agents/scripts/validate_state.py passes (OK, validated 1 file(s)); no schema or state-file structure changed.
  • Verified the trigger logic matches the bundled CLI's existing pristine detection (cli/src/lib/project.ts readProjectName rejects values containing [).
  • Verified no em or en dashes were introduced in prose (only the §P10 section heading keeps the §PN — Title convention shared by every other section heading in the file).
  • Confirmed the sentinel does not reach consumers: copy-paste install copies only .agents/ plus CLAUDE.md plus AGENTS.md, and cli/scripts/sync-templates.mjs bundles only those same paths.

Checklist

  • Code follows project conventions
  • Tests added/updated (if applicable) — none needed; rules-text change, no runtime code
  • Documentation updated (README, CORE_RULES, meta-repo module)
  • Protocol files follow defined schemas (.agents/ was modified; validator passes)

@leonardobuares leonardobuares changed the title feat: add first-run setup interview gate (PROTOCOL_RULES §P10) (#21) feat: add first-run setup interview gate (PROTOCOL_RULES §P10) Jun 17, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ba8dd3f2f0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread README.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat: mandatory first-run setup interview for unconfigured projects

1 participant