onboard

name	onboard
description	Use at session start to detect available skills, load active context, and enforce skill usage discipline for the current session.
effort	medium
argument-hint	null

Onboard

Purpose

Framework bootstrap and enforcement. Detects available skills, loads active context (spec, tasks, decisions), presents quick status, and enforces skill usage discipline. Prevents agents from bypassing skills with rationalizations.

Trigger

• Auto-triggered via SessionStart hook
• Manual: /ai-onboard
• Context: beginning of any non-trivial session.

Procedure

1. Detect skills -- scan .agents/skills/ for available SKILL.md files. Build a capability map.

2. Load active context:

   • Read .ai-engineering/specs/spec.md -- current spec
   • Read .ai-engineering/specs/plan.md -- current tasks
   • Read .ai-engineering/state/decision-store.json -- active decisions and risk acceptances
   • Read .ai-engineering/contexts/team/lessons.md -- accumulated rules and patterns

3. Present status -- concise summary to user:

   Active spec: spec-054 (Hooks, Security, Observability)
   Tasks: 12/18 complete, 2 blocked
   Decisions: 3 active, 1 expiring in 5 days
   Skills: 29 loaded
   

4. Enforce skill discipline -- install the following rule for the session:

   If a skill applies to the current task, you MUST use it. No exceptions. No "this is too simple" shortcuts.

Red Flags Table

Rationalization patterns agents use to skip skills. Every one of these is wrong.

#	Rationalization	Why it is wrong	Correct action
1	"This is too simple for planning"	Simple tasks still need scope definition	Use /ai-plan (trivial pipeline)
2	"I'll just make a quick fix"	Quick fixes skip root cause analysis	Use /ai-debug
3	"Tests aren't needed for this change"	Every behavioral change needs verification	Use /ai-test
4	"I already know the answer"	Confidence without verification is the #1 source of bugs	Use /ai-explore first
5	"The user is in a hurry"	Skipping process creates more delay from rework	Follow the process faster, do not skip steps
6	"This is just a config change"	Config changes affect runtime behavior	Use /ai-test to verify
7	"I'll add tests later"	Later never comes; RED before GREEN	TDD protocol: tests first
8	"The existing tests cover this"	Assumption without verification	Run tests, check coverage
9	"This doesn't need a spec"	Every pipeline requires a spec, even trivial	Use /ai-brainstorm
10	"I'll clean up the commit message later"	Commit messages are permanent documentation	Use /ai-commit
11	"Security scanning would slow us down"	A leaked secret takes hours to rotate	Gitleaks runs in seconds
12	"This refactor is obvious"	Obvious refactors still need test verification	Use /ai-simplify

Detection Rules

When the user's request matches these patterns, enforce the corresponding skill:

User intent pattern	Required skill
"implement", "build", "add feature"	/ai-plan then /ai-dispatch
"fix", "bug", "broken", "not working"	/ai-debug
"test", "coverage", "verify"	/ai-test
"refactor", "restructure", "move"	/ai-simplify
"explain", "how does", "what is"	/ai-explain
"commit", "push", "save"	/ai-commit
"PR", "pull request", "review"	/ai-pr
"deploy", "release", "publish"	/ai-release
"conflict", "merge conflict"	/ai-resolve-conflicts
"incident", "outage", "postmortem"	/ai-postmortem

Quick Reference

/ai-onboard     # manual bootstrap (usually auto-triggered)

No arguments. Reads project state and configures the session.

Boundaries

• Onboard is read-only -- it does not modify project files
• It does not execute tasks -- it configures the session for correct execution
• If no active spec exists, report it but do not block the session

$ARGUMENTS