@@ -19,7 +19,7 @@ Keep this managed block so 'openspec update' can refresh the instructions.
1919
2020<!-- GOVERNANCE:START -->
2121## Governance
22- Task lifecycle, quality gates, lesson detection: managed by ` sidstack-aware ` skill. Use ` /sidstack-dev ` for structured workflows. SidStack MCP tasks (` mcp__sidstack__task_* ` ) for persistence; built-in tasks for session-local sub-steps only.
22+ Task lifecycle, quality gates, lesson detection: managed by ` sidstack-aware ` skill. Every request is ** classified by intent first ** (via Workflow Router + sidstack-aware skill), then routed to the correct workflow. Use ` /sidstack-dev ` for explicit structured workflows. SidStack MCP tasks (` mcp__sidstack__task_* ` ) for persistence; built-in tasks for session-local sub-steps only.
2323
2424** Integrated workflow — always follow this pattern:**
25251 . ** Before work:** ` knowledge_search ` + ` memory_search ` → find context. ` entity_link ` → link relevant docs to task.
@@ -29,6 +29,71 @@ Task lifecycle, quality gates, lesson detection: managed by `sidstack-aware` ski
2929
3030# SidStack - Claude Code Instructions
3131
32+ ## SidStack Governance
33+
34+ This project uses ** SidStack** for task tracking, knowledge management, and quality enforcement.
35+
36+ ---
37+
38+ ## CRITICAL RULES
39+
40+ ** 1. QUALITY BEFORE COMPLETE**
41+ - Run project's test/build commands before marking task done
42+ - Verify the change works at runtime (not just static checks)
43+ - Never mark completed if tests fail
44+
45+ ** 2. ASK WHEN UNCLEAR**
46+ - Don't guess requirements - ask the user
47+ - Don't assume scope - clarify before expanding
48+
49+ ---
50+
51+ ## Session Start
52+
53+ At the beginning of each session, check for active work:
54+ ```
55+ task_list({ projectId: "sidstack", preset: "actionable" })
56+ ```
57+ If there's an in_progress task, resume it. Otherwise, show pending tasks.
58+
59+ ---
60+
61+ ## Workflow Router
62+
63+ Classify every user request before acting. Match ** semantic intent** , not keywords.
64+
65+ | User wants to... | Workflow | Action |
66+ | -----------------| ----------| --------|
67+ | Ask, discuss, explore ideas | ** discuss** | Answer directly. No task needed. |
68+ | Create, list, or check task status | ** track** | ` task_list ` / ` task_create ` / ` task_update ` only |
69+ | Fix critical production issue NOW | ** hotfix** | ` task_create(bugfix, critical) ` → ` /sidstack-dev hotfix ` |
70+ | Fix a bug, error, broken behavior | ** bugfix** | ` task_create(bugfix) ` → ` /sidstack-dev fix ` |
71+ | Build new feature or capability | ** implement** | ` task_create(feature) ` → ` /sidstack-dev feature ` |
72+ | Refactor, optimize, clean up code | ** improve** | ` task_create(refactor/perf/debt) ` → ` /sidstack-dev feature ` |
73+ | Review code or audit existing work | ** review** | ` /sidstack-dev review ` |
74+ | Process a ticket from queue | ** ticket** | ` /sidstack ticket <id> ` |
75+ | Build or update documentation/knowledge | ** knowledge** | ` /sidstack-knowledge ` |
76+ | Record lessons from incidents | ** learn** | ` incident_create ` → ` lesson_create ` |
77+
78+ ### Classification Rules
79+
80+ 1 . ** Intent over keywords.** "Fix the tests" = bugfix. "Add tests" = implement. "Why do tests fail?" = discuss.
81+ 2 . ** Urgency splits hotfix from bugfix.** Hotfix = production is broken NOW. Bugfix = known issue, can plan.
82+ 3 . ** Any language.** Classify by meaning — works in Vietnamese, English, etc.
83+ 4 . ** When ambiguous** — ask user: "This could be [ X] or [ Y] , which fits?"
84+ 5 . ** Explicit ` /sidstack-dev ` always wins** over this router.
85+
86+ ### Task Size → Flow Depth
87+
88+ | Size | Criteria | Flow |
89+ | ------| ----------| ------|
90+ | ** Trivial** | Typo, config, <5 lines | No task. Just do it. |
91+ | ** Small** | Bug fix, single-file | ` task_create ` → implement → ` task_complete ` |
92+ | ** Medium** | Multi-file feature | ` task_create ` → ` entity_context ` → implement → test → ` task_complete ` |
93+ | ** Large** | Architecture change | ` /sidstack-dev feature ` (full 4-step with plan review) |
94+
95+ ---
96+
3297## Project Overview
3398** SidStack** = AI-Powered Project Intelligence Platform
3499Core: Knowledge System, Impact Analysis, Task Management, Ticket Queue, Training Room.
@@ -78,6 +143,77 @@ pnpm typecheck # Type checking
78143** Impact:** ` impact_analyze ` → ` impact_check_gate ` . Gates: ` blocked ` , ` warning ` , ` clear ` .
79144** Tickets:** ` new → reviewing → approved → in_progress → completed ` (or ` rejected ` ).
80145
146+ ---
147+
148+ ## SidStack Tools Reference
149+
150+ | Workflow Moment | Tool | Purpose |
151+ | ----------------| ------| ---------|
152+ | ** Starting Work** | ` task_list(preset: "actionable") ` | See what needs doing |
153+ | | ` entity_context(entityType: "task", entityId: taskId) ` | Load ALL linked context in one call |
154+ | | ` task_create(projectId, title, taskType) ` | Create new task |
155+ | ** During Work** | ` task_update(taskId, progress: 0-100) ` | Track progress |
156+ | | ` impact_analyze(description, targetFiles) ` | Before touching core/risky code |
157+ | | ` knowledge_search(query) ` | Find project patterns, docs |
158+ | ** Finishing Work** | ` task_complete(taskId) ` | After quality gates pass |
159+ | | ` memory_add(content, projectId) ` | Store learnings for future |
160+ | | ` lesson_create(...) ` | After fixing tricky bugs (ask user first) |
161+
162+ > ** Tip:** ` entity_context ` loads everything linked to a task (knowledge, memory, references) in one call — use it instead of calling ` knowledge_search ` + ` memory_search ` + ` entity_references ` separately.
163+
164+ ---
165+
166+ ## Slash Commands
167+
168+ | Command | Purpose |
169+ | ---------| ---------|
170+ | ` /sidstack ` | Dashboard - tasks, tickets, focus, governance |
171+ | ` /sidstack:knowledge ` | Knowledge system - search, explore, build context |
172+ | ` /sidstack:agent ` | Spawn governed agent (worker/reviewer) |
173+
174+ ---
175+
176+ ## Quality Checks
177+
178+ Run before completing any task:
179+ ``` bash
180+ pnpm test
181+ pnpm packages:build
182+ pnpm typecheck
183+ ```
184+
185+ ---
186+
187+ ## Common Mistakes to Avoid
188+
189+ | Mistake | Consequence | Correct Approach |
190+ | ---------| -------------| ------------------|
191+ | Skip task_create for "quick fix" | No audit trail, no acceptance criteria | Always create task, even for small changes |
192+ | Mark complete before testing | Broken code merged | Run tests + verify runtime first |
193+ | Expand scope without asking | Wasted effort, wrong direction | Clarify with user before expanding |
194+ | Ignore existing knowledge | Reinvent patterns, miss constraints | Call ` knowledge_search ` before implementing |
195+
196+ ---
197+
198+ ## Task Systems: SidStack MCP vs Built-in
199+
200+ | System | Use For |
201+ | --------| ---------|
202+ | ** SidStack MCP** (` mcp__sidstack__task_* ` ) | Governance, quality gates, cross-session persistence |
203+ | ** Built-in** (` TaskCreate/TaskUpdate ` ) | Session-local sub-step coordination |
204+
205+ Rule: Always create the SidStack MCP task first (for governance), then optionally use built-in tasks for sub-steps.
206+
207+ ---
208+
209+ ## Agent Teams
210+
211+ For multi-agent orchestration with Worker + Reviewer teammates:
212+ - Use ` /sidstack:agent ` slash command to spawn governed agents
213+ - See ` .sidstack/governance.md ` for spawn templates and orchestration workflow
214+
215+ ---
216+
81217<!-- DOCUMENTATION-DISCIPLINE:START -->
82218## MANDATORY: Documentation Discipline
83219
@@ -107,3 +243,12 @@ pnpm typecheck # Type checking
1072431 . Add Neo4j, Qdrant, or Go service dependencies
1082442 . Skip quality gates
1092453 . Create tasks without analysis
246+
247+ ---
248+
249+ ## More Details
250+
251+ For comprehensive governance documentation:
252+ - ` .sidstack/governance.md ` - Full governance rules, agent teams guide
253+ - ` .claude/skills/ ` - Auto-triggered Claude Code skills
254+ - ` .claude/agents/ ` - Role-specific agent definitions (Worker, Reviewer)
0 commit comments