| 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
-
Detect skills -- scan .agents/skills/ for available SKILL.md files. Build a capability map.
-
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
-
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
-
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
