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 .claude/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
1---2name: ai-onboard3description: Use at session start to detect available skills, load active context, and enforce skill usage discipline for the current session.4---5
6
7# Onboard
8
9## Purpose
10
11Framework 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.
12
13## Trigger
14
15- Auto-triggered via SessionStart hook
16- Manual: `/ai-onboard`
17- Context: beginning of any non-trivial session.
18
19## Procedure
20
211. **Detect skills** -- scan `.claude/skills/` for available SKILL.md files. Build a capability map.
22
232. **Load active context**:
24 - Read `.ai-engineering/specs/spec.md` -- current spec
25 - Read `.ai-engineering/specs/plan.md` -- current tasks
26 - Read `.ai-engineering/state/decision-store.json` -- active decisions and risk acceptances
27 - Read `.ai-engineering/contexts/team/lessons.md` -- accumulated rules and patterns
28
293. **Present status** -- concise summary to user:
30 ```
31 Active spec: spec-054 (Hooks, Security, Observability)
32 Tasks: 12/18 complete, 2 blocked
33 Decisions: 3 active, 1 expiring in 5 days
34 Skills: 29 loaded
35 ```
36
374. **Enforce skill discipline** -- install the following rule for the session:
38
39 > **If a skill applies to the current task, you MUST use it.** No exceptions. No "this is too simple" shortcuts.
40
41## Red Flags Table
42
43Rationalization patterns agents use to skip skills. Every one of these is wrong.
44
45| # | Rationalization | Why it is wrong | Correct action |
46|---|----------------|-----------------|----------------|
47| 1 | "This is too simple for planning" | Simple tasks still need scope definition | Use `/ai-plan` (trivial pipeline) |
48| 2 | "I'll just make a quick fix" | Quick fixes skip root cause analysis | Use `/ai-debug` |
49| 3 | "Tests aren't needed for this change" | Every behavioral change needs verification | Use `/ai-test` |
50| 4 | "I already know the answer" | Confidence without verification is the #1 source of bugs | Use `/ai-explore` first |
51| 5 | "The user is in a hurry" | Skipping process creates more delay from rework | Follow the process faster, do not skip steps |
52| 6 | "This is just a config change" | Config changes affect runtime behavior | Use `/ai-test` to verify |
53| 7 | "I'll add tests later" | Later never comes; RED before GREEN | TDD protocol: tests first |
54| 8 | "The existing tests cover this" | Assumption without verification | Run tests, check coverage |
55| 9 | "This doesn't need a spec" | Every pipeline requires a spec, even trivial | Use `/ai-brainstorm` |
56| 10 | "I'll clean up the commit message later" | Commit messages are permanent documentation | Use `/ai-commit` |
57| 11 | "Security scanning would slow us down" | A leaked secret takes hours to rotate | Gitleaks runs in seconds |
58| 12 | "This refactor is obvious" | Obvious refactors still need test verification | Use `/ai-simplify` |
59
60## Detection Rules
61
62When the user's request matches these patterns, enforce the corresponding skill:
63
64| User intent pattern | Required skill |
65|-------------------|----------------|
66| "implement", "build", "add feature" | `/ai-plan` then `/ai-dispatch` |
67| "fix", "bug", "broken", "not working" | `/ai-debug` |
68| "test", "coverage", "verify" | `/ai-test` |
69| "refactor", "restructure", "move" | `/ai-simplify` |
70| "explain", "how does", "what is" | `/ai-explain` |
71| "commit", "push", "save" | `/ai-commit` |
72| "PR", "pull request", "review" | `/ai-pr` |
73| "deploy", "release", "publish" | `/ai-release` |
74| "conflict", "merge conflict" | `/ai-resolve-conflicts` |
75| "incident", "outage", "postmortem" | `/ai-postmortem` |
76
77## Quick Reference
78
79```
80/ai-onboard # manual bootstrap (usually auto-triggered)
81```
82
83No arguments. Reads project state and configures the session.
84
85## Boundaries
86
87- Onboard is read-only -- it does not modify project files
88- It does not execute tasks -- it configures the session for correct execution
89- If no active spec exists, report it but do not block the session
90
91$ARGUMENTS
majiayu000