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