Skip to content

feat(#32): /setup first-run bootstrap + deprecate /onboard + update CLAUDE.md#33

Merged
atlas-apex merged 1 commit into
mainfrom
feature/GH-32-setup-skill
Apr 12, 2026
Merged

feat(#32): /setup first-run bootstrap + deprecate /onboard + update CLAUDE.md#33
atlas-apex merged 1 commit into
mainfrom
feature/GH-32-setup-skill

Conversation

@atlas-apex

Copy link
Copy Markdown
Collaborator

Summary

New `/setup` skill for first-run bootstrap — "describe your stack, accept defaults, done in 3 exchanges." Replaces the 7-question sequential `/onboard` flow. `onboarding-check.sh` now checks `onboarding.yaml` (committed) instead of a gitignored session marker.

Closes #32

Design

Skill Scope Writes to When
`/setup` (new) Framework-level `onboarding.yaml` Once per fork
`/handover` (existing) Project-level `project-config.json` Once per managed project
`/onboard` (deprecated) Redirect only

Changes

  • New `.claude/skills/setup/SKILL.md` — "describe, propose, confirm" UX. Parses natural-language stack description, maps to `onboarding.yaml` fields, proposes complete config, one yes/no confirm. Stages but doesn't commit. Idempotent + `--reset` support.
  • `.claude/hooks/onboarding-check.sh` — now checks `onboarding.yaml` for placeholder "Your Company Name" instead of the `.claude/session/onboarded` marker. Config file IS the flag — committed, persists across clones, no hidden state.
  • `.claude/skills/onboard/SKILL.md` — replaced with a redirect page pointing at `/setup` and `/handover`.
  • `CLAUDE.md` — skills table updated: 13 → 17 skills, hooks description updated (14 hooks, 3 event types), rules count updated (9 files).

Glossary

Term Definition
/setup First-run bootstrap skill. Configures `onboarding.yaml` for a new ApexStack fork in 3 exchanges.
Placeholder detection The SessionStart hook greps `onboarding.yaml` for "Your Company Name". If found → prompt /setup. If real value → silent.
Describe-propose-confirm The UX pattern: one open-ended question → one proposed config → one yes/no. Replaces sequential interrogation.

Test plan

  • Fresh fork with template `onboarding.yaml` → SessionStart hook prompts `/setup`
  • After `/setup` fills in real values → hook goes silent
  • Running `/onboard` shows the deprecation redirect
  • CLAUDE.md skills table counts match reality (17 skills, 14 hooks)
  • Rex review
  • Explicit per-PR CEO approval

🤖 Generated with Claude Code

…s table

Introduces the first-run bootstrap experience for new ApexStack forks.
Three exchanges instead of eight questions: "describe your stack",
"here are the defaults", "accept or customize?"

Design split:
- /setup = framework-level (once per fork, writes onboarding.yaml)
- /handover = project-level (once per project, writes project-config)
- /onboard = deprecated, redirects to /setup or /handover

## /setup skill

.claude/skills/setup/SKILL.md — the "describe, propose, confirm"
flow. Reads the user's natural-language stack description, maps to
onboarding.yaml fields, proposes a complete config, asks for one
yes/no confirmation. Stages but does not commit — lets the user
review the diff first. Idempotent (re-run shows current config and
asks what to update). Supports --reset to clear and start fresh.

## onboarding-check.sh update

Changed detection from the gitignored .claude/session/onboarded
marker to checking onboarding.yaml for placeholder values (grep
for "Your Company Name"). The config file IS the flag — committed,
persists across clones, no hidden state. New users see "run /setup";
configured forks see nothing.

## /onboard deprecation

Replaced the 130-line discovery flow with a redirect page pointing
at /setup (framework config) and /handover (project config). The
split resolves the mixed-concerns problem: framework bootstrap and
per-project discovery are different flows that happen at different
times, write to different files, and have different triggers.

## CLAUDE.md updates

- Skills table: 13 → 17 (added /setup, /start-ticket, /approve-merge,
  /approve-design; /onboard still listed but marked deprecated)
- Hooks description: updated count and expanded capability summary
- Rules count: 9 (added ticket-vocabulary.md)
- Settings description: now mentions PostToolUse and SessionStart
  events in addition to PreToolUse

Closes #32

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

@atlas-apex atlas-apex left a comment

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Code Review: PR #33

Commit: 16ffd6eb2d2e753baea8c9014cb44ed458e39396

Summary

Replaces sequential /onboard with a 3-exchange /setup skill. Hook now checks committed onboarding.yaml instead of a gitignored session marker. Clean separation: /setup = framework, /handover = project.

Checklist Results

  • N/A Architecture & DDD: docs/config only
  • ✅ Code Quality: clear, well-structured
  • N/A Testing: no runtime code
  • ✅ Security: no secrets, no injection vectors
  • N/A Performance: shell + markdown only
  • ✅ PR Description & Glossary: present and thorough
  • ✅ Technical Decisions (AgDR): N/A — no library/framework choices

Issues Found

  1. Hook grep pattern mismatchonboarding-check.sh greps for "Your Company Name" (double quotes), but YAML files typically use unquoted or single-quoted strings. Verify the template onboarding.yaml uses exactly that double-quoted form, otherwise the hook will silently pass on unconfigured forks.

Suggestions

  • Minor: the exit 0 after the fi block runs even on the prompt path — harmless but the exit could move inside the else branch for clarity.

Verdict

COMMENT — one item to verify (grep pattern vs actual template format), otherwise clean.


🤖 Reviewed by Rex (Code Reviewer Agent)
📌 Reviewed commit: 16ffd6eb2d2e753baea8c9014cb44ed458e39396

@atlas-apex atlas-apex merged commit 086013c into main Apr 12, 2026
3 of 4 checks passed
@me2resh me2resh deleted the feature/GH-32-setup-skill branch June 5, 2026 16:52
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feat] /setup — first-run framework bootstrap + fold /onboard into /idea and /handover

2 participants