@mindfoldhq/trellis 0.3.0-rc.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/README.md +16 -4
  2. package/dist/cli/index.js +4 -0
  3. package/dist/cli/index.js.map +1 -1
  4. package/dist/commands/init.d.ts +4 -0
  5. package/dist/commands/init.d.ts.map +1 -1
  6. package/dist/commands/init.js +29 -15
  7. package/dist/commands/init.js.map +1 -1
  8. package/dist/commands/update.d.ts.map +1 -1
  9. package/dist/commands/update.js +19 -11
  10. package/dist/commands/update.js.map +1 -1
  11. package/dist/configurators/antigravity.d.ts +8 -0
  12. package/dist/configurators/antigravity.d.ts.map +1 -0
  13. package/dist/configurators/antigravity.js +18 -0
  14. package/dist/configurators/antigravity.js.map +1 -0
  15. package/dist/configurators/gemini.d.ts +8 -0
  16. package/dist/configurators/gemini.d.ts.map +1 -0
  17. package/dist/configurators/gemini.js +52 -0
  18. package/dist/configurators/gemini.js.map +1 -0
  19. package/dist/configurators/index.d.ts.map +1 -1
  20. package/dist/configurators/index.js +49 -1
  21. package/dist/configurators/index.js.map +1 -1
  22. package/dist/configurators/kilo.d.ts +8 -0
  23. package/dist/configurators/kilo.d.ts.map +1 -0
  24. package/dist/configurators/kilo.js +51 -0
  25. package/dist/configurators/kilo.js.map +1 -0
  26. package/dist/configurators/kiro.d.ts +8 -0
  27. package/dist/configurators/kiro.d.ts.map +1 -0
  28. package/dist/configurators/kiro.js +20 -0
  29. package/dist/configurators/kiro.js.map +1 -0
  30. package/dist/migrations/manifests/0.3.0-rc.6.json +9 -0
  31. package/dist/migrations/manifests/0.3.0.json +11 -0
  32. package/dist/templates/antigravity/index.d.ts +12 -0
  33. package/dist/templates/antigravity/index.d.ts.map +1 -0
  34. package/dist/templates/antigravity/index.js +29 -0
  35. package/dist/templates/antigravity/index.js.map +1 -0
  36. package/dist/templates/claude/agents/implement.md +1 -1
  37. package/dist/templates/claude/commands/trellis/brainstorm.md +16 -18
  38. package/dist/templates/claude/commands/trellis/start.md +73 -48
  39. package/dist/templates/codex/skills/brainstorm/SKILL.md +16 -18
  40. package/dist/templates/codex/skills/start/SKILL.md +80 -46
  41. package/dist/templates/cursor/commands/trellis-brainstorm.md +16 -18
  42. package/dist/templates/cursor/commands/trellis-start.md +191 -23
  43. package/dist/templates/extract.d.ts +52 -0
  44. package/dist/templates/extract.d.ts.map +1 -1
  45. package/dist/templates/extract.js +90 -0
  46. package/dist/templates/extract.js.map +1 -1
  47. package/dist/templates/gemini/commands/trellis/before-backend-dev.toml +17 -0
  48. package/dist/templates/gemini/commands/trellis/before-frontend-dev.toml +17 -0
  49. package/dist/templates/gemini/commands/trellis/brainstorm.toml +420 -0
  50. package/dist/templates/gemini/commands/trellis/break-loop.toml +129 -0
  51. package/dist/templates/gemini/commands/trellis/check-backend.toml +17 -0
  52. package/dist/templates/gemini/commands/trellis/check-cross-layer.toml +147 -0
  53. package/dist/templates/gemini/commands/trellis/check-frontend.toml +17 -0
  54. package/dist/templates/gemini/commands/trellis/create-command.toml +119 -0
  55. package/dist/templates/gemini/commands/trellis/finish-work.toml +133 -0
  56. package/dist/templates/gemini/commands/trellis/integrate-skill.toml +104 -0
  57. package/dist/templates/gemini/commands/trellis/onboard.toml +111 -0
  58. package/dist/templates/gemini/commands/trellis/record-session.toml +66 -0
  59. package/dist/templates/gemini/commands/trellis/start.toml +292 -0
  60. package/dist/templates/gemini/commands/trellis/update-spec.toml +132 -0
  61. package/dist/templates/gemini/index.d.ts +21 -0
  62. package/dist/templates/gemini/index.d.ts.map +1 -0
  63. package/dist/templates/gemini/index.js +44 -0
  64. package/dist/templates/gemini/index.js.map +1 -0
  65. package/dist/templates/iflow/agents/implement.md +1 -1
  66. package/dist/templates/iflow/commands/trellis/brainstorm.md +16 -18
  67. package/dist/templates/iflow/commands/trellis/finish-work.md +9 -0
  68. package/dist/templates/iflow/commands/trellis/start.md +108 -50
  69. package/dist/templates/iflow/index.d.ts +3 -2
  70. package/dist/templates/iflow/index.d.ts.map +1 -1
  71. package/dist/templates/iflow/index.js +7 -9
  72. package/dist/templates/iflow/index.js.map +1 -1
  73. package/dist/templates/kilo/commands/trellis/before-backend-dev.md +13 -0
  74. package/dist/templates/kilo/commands/trellis/before-frontend-dev.md +13 -0
  75. package/dist/templates/kilo/commands/trellis/brainstorm.md +474 -0
  76. package/dist/templates/kilo/commands/trellis/break-loop.md +125 -0
  77. package/dist/templates/kilo/commands/trellis/check-backend.md +13 -0
  78. package/dist/templates/kilo/commands/trellis/check-cross-layer.md +153 -0
  79. package/dist/templates/kilo/commands/trellis/check-frontend.md +13 -0
  80. package/dist/templates/kilo/commands/trellis/create-command.md +152 -0
  81. package/dist/templates/kilo/commands/trellis/finish-work.md +129 -0
  82. package/dist/templates/kilo/commands/trellis/integrate-skill.md +219 -0
  83. package/dist/templates/kilo/commands/trellis/onboard.md +358 -0
  84. package/dist/templates/kilo/commands/trellis/parallel.md +194 -0
  85. package/dist/templates/kilo/commands/trellis/record-session.md +62 -0
  86. package/dist/templates/kilo/commands/trellis/start.md +321 -0
  87. package/dist/templates/kilo/commands/trellis/update-spec.md +285 -0
  88. package/dist/templates/kilo/index.d.ts +16 -0
  89. package/dist/templates/kilo/index.d.ts.map +1 -0
  90. package/dist/templates/kilo/index.js +39 -0
  91. package/dist/templates/kilo/index.js.map +1 -0
  92. package/dist/templates/kiro/index.d.ts +18 -0
  93. package/dist/templates/kiro/index.d.ts.map +1 -0
  94. package/dist/templates/kiro/index.js +40 -0
  95. package/dist/templates/kiro/index.js.map +1 -0
  96. package/dist/templates/kiro/skills/before-backend-dev/SKILL.md +18 -0
  97. package/dist/templates/kiro/skills/before-frontend-dev/SKILL.md +18 -0
  98. package/dist/templates/kiro/skills/brainstorm/SKILL.md +479 -0
  99. package/dist/templates/kiro/skills/break-loop/SKILL.md +130 -0
  100. package/dist/templates/kiro/skills/check-backend/SKILL.md +18 -0
  101. package/dist/templates/kiro/skills/check-cross-layer/SKILL.md +158 -0
  102. package/dist/templates/kiro/skills/check-frontend/SKILL.md +18 -0
  103. package/dist/templates/kiro/skills/create-command/SKILL.md +101 -0
  104. package/dist/templates/kiro/skills/finish-work/SKILL.md +148 -0
  105. package/dist/templates/kiro/skills/integrate-skill/SKILL.md +221 -0
  106. package/dist/templates/kiro/skills/onboard/SKILL.md +363 -0
  107. package/dist/templates/kiro/skills/record-session/SKILL.md +67 -0
  108. package/dist/templates/kiro/skills/start/SKILL.md +330 -0
  109. package/dist/templates/kiro/skills/update-spec/SKILL.md +335 -0
  110. package/dist/templates/opencode/agents/implement.md +1 -1
  111. package/dist/templates/opencode/agents/research.md +1 -2
  112. package/dist/templates/opencode/commands/trellis/brainstorm.md +16 -18
  113. package/dist/templates/opencode/commands/trellis/start.md +71 -48
  114. package/dist/templates/trellis/scripts/common/cli_adapter.py +100 -12
  115. package/dist/templates/trellis/scripts/common/registry.py +1 -1
  116. package/dist/templates/trellis/scripts/task.py +1 -8
  117. package/dist/types/ai-tools.d.ts +4 -4
  118. package/dist/types/ai-tools.d.ts.map +1 -1
  119. package/dist/types/ai-tools.js +32 -0
  120. package/dist/types/ai-tools.js.map +1 -1
  121. package/package.json +3 -2
@@ -0,0 +1,111 @@
1
+ description = "Onboard a new team member to the Trellis AI-assisted workflow system"
2
+
3
+ prompt = """
4
+ You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
5
+
6
+ YOUR ROLE: Be a mentor and teacher. Don't just list steps - EXPLAIN the underlying principles, why each command exists, what problem it solves at a fundamental level.
7
+
8
+ ## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
9
+
10
+ This onboarding has THREE equally important parts:
11
+
12
+ **PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
13
+ - Explain WHY this workflow exists
14
+ - Explain WHAT each command does and WHY
15
+
16
+ **PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
17
+ - Walk through ALL 5 examples in detail
18
+ - For EACH step in EACH example, explain:
19
+ - PRINCIPLE: Why this step exists
20
+ - WHAT HAPPENS: What the command actually does
21
+ - IF SKIPPED: What goes wrong without it
22
+
23
+ **PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
24
+ - Check if project guidelines are still empty templates
25
+ - If empty, guide the developer to fill them with project-specific content
26
+ - Explain the customization workflow
27
+
28
+ DO NOT skip any part. All three parts are essential.
29
+
30
+ After completing ALL THREE parts, ask the developer about their first task.
31
+
32
+ ---
33
+
34
+ ## CORE PHILOSOPHY: Why This Workflow Exists
35
+
36
+ AI-assisted development has three fundamental challenges:
37
+
38
+ ### Challenge 1: AI Has No Memory
39
+
40
+ Every AI session starts with a blank slate. The `.trellis/workspace/` system captures what happened in each session. The `/trellis:start` command reads this history at session start, giving AI "artificial memory."
41
+
42
+ ### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
43
+
44
+ The `.trellis/spec/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
45
+
46
+ ### Challenge 3: AI Context Window Is Limited
47
+
48
+ The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/trellis:finish-work` command does a final holistic review.
49
+
50
+ ---
51
+
52
+ ## SYSTEM STRUCTURE
53
+
54
+ ```
55
+ .trellis/
56
+ |-- .developer # Your identity (gitignored)
57
+ |-- workflow.md # Complete workflow documentation
58
+ |-- workspace/ # "AI Memory" - session history
59
+ |-- tasks/ # Task tracking (unified)
60
+ |-- spec/ # "AI Training Data" - project knowledge
61
+ | |-- frontend/ # Frontend conventions
62
+ | |-- backend/ # Backend conventions
63
+ | +-- guides/ # Thinking patterns
64
+ +-- scripts/ # Automation tools
65
+ ```
66
+
67
+ ---
68
+
69
+ ## COMMAND DEEP DIVE
70
+
71
+ ### /trellis:start - Restore AI Memory
72
+ ### /trellis:before-frontend-dev and /trellis:before-backend-dev - Inject Specialized Knowledge
73
+ ### /trellis:check-frontend and /trellis:check-backend - Combat Context Drift
74
+ ### /trellis:check-cross-layer - Multi-Dimension Verification
75
+ ### /trellis:finish-work - Holistic Pre-Commit Review
76
+ ### /trellis:record-session - Persist Memory for Future
77
+
78
+ ---
79
+
80
+ ## REAL-WORLD WORKFLOW EXAMPLES
81
+
82
+ ### Example 1: Bug Fix Session
83
+ ### Example 2: Planning Session (No Code)
84
+ ### Example 3: Code Review Fixes
85
+ ### Example 4: Large Refactoring
86
+ ### Example 5: Debug Session
87
+
88
+ Walk through each example explaining every step.
89
+
90
+ ---
91
+
92
+ ## KEY RULES TO EMPHASIZE
93
+
94
+ 1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
95
+ 2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
96
+ 3. **Check after code** - /check-* commands catch context drift.
97
+ 4. **Record everything** - /trellis:record-session persists memory.
98
+
99
+ ---
100
+
101
+ # PART 3: Customize Your Development Guidelines
102
+
103
+ Check if `.trellis/spec/` contains empty templates or customized guidelines:
104
+
105
+ ```bash
106
+ grep -l "To be filled by the team" .trellis/spec/backend/*.md 2>/dev/null | wc -l
107
+ grep -l "To be filled by the team" .trellis/spec/frontend/*.md 2>/dev/null | wc -l
108
+ ```
109
+
110
+ If empty templates, guide filling them. If already customized, proceed with first task.
111
+ """
@@ -0,0 +1,66 @@
1
+ description = "Record work progress after human has tested and committed code"
2
+
3
+ prompt = """
4
+ [!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
5
+
6
+ **AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
7
+
8
+ ---
9
+
10
+ ## Record Work Progress (Simplified - Only 2 Steps)
11
+
12
+ ### Step 1: Get Context
13
+
14
+ ```bash
15
+ python3 ./.trellis/scripts/get_context.py
16
+ ```
17
+
18
+ ### Step 2: One-Click Add Session
19
+
20
+ ```bash
21
+ # Method 1: Simple parameters
22
+ python3 ./.trellis/scripts/add_session.py \\
23
+ --title "Session Title" \\
24
+ --commit "hash1,hash2" \\
25
+ --summary "Brief summary of what was done"
26
+
27
+ # Method 2: Pass detailed content via stdin
28
+ cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --title "Title" --commit "hash"
29
+ | Feature | Description |
30
+ |---------|-------------|
31
+ | New API | Added user authentication endpoint |
32
+ | Frontend | Updated login form |
33
+
34
+ **Updated Files**:
35
+ - `packages/api/modules/auth/router.ts`
36
+ - `apps/web/modules/auth/components/login-form.tsx`
37
+ EOF
38
+ ```
39
+
40
+ **Auto-completes**:
41
+ - [OK] Appends session to journal-N.md
42
+ - [OK] Auto-detects line count, creates new file if >2000 lines
43
+ - [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
44
+
45
+ ---
46
+
47
+ ## Archive Completed Task (if any)
48
+
49
+ If a task was completed this session:
50
+
51
+ ```bash
52
+ python3 ./.trellis/scripts/task.py archive <task-name>
53
+ ```
54
+
55
+ ---
56
+
57
+ ## Script Command Reference
58
+
59
+ | Command | Purpose |
60
+ |---------|---------|
61
+ | `python3 ./.trellis/scripts/get_context.py` | Get all context info |
62
+ | `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended)** |
63
+ | `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create new task directory |
64
+ | `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task |
65
+ | `python3 ./.trellis/scripts/task.py list` | List active tasks |
66
+ """
@@ -0,0 +1,292 @@
1
+ description = "Initialize your AI development session and begin working on tasks"
2
+
3
+ prompt = """
4
+ # Start Session
5
+
6
+ Initialize your AI development session and begin working on tasks.
7
+
8
+ ---
9
+
10
+ ## Operation Types
11
+
12
+ | Marker | Meaning | Executor |
13
+ |--------|---------|----------|
14
+ | `[AI]` | Bash scripts or Task calls executed by AI | You (AI) |
15
+ | `[USER]` | Slash commands executed by user | User |
16
+
17
+ ---
18
+
19
+ ## Initialization `[AI]`
20
+
21
+ ### Step 1: Understand Development Workflow
22
+
23
+ First, read the workflow guide to understand the development process:
24
+
25
+ ```bash
26
+ cat .trellis/workflow.md
27
+ ```
28
+
29
+ **Follow the instructions in workflow.md** - it contains:
30
+ - Core principles (Read Before Write, Follow Standards, etc.)
31
+ - File system structure
32
+ - Development process
33
+ - Best practices
34
+
35
+ ### Step 2: Get Current Context
36
+
37
+ ```bash
38
+ python3 ./.trellis/scripts/get_context.py
39
+ ```
40
+
41
+ This shows: developer identity, git status, current task (if any), active tasks.
42
+
43
+ ### Step 3: Read Guidelines Index
44
+
45
+ ```bash
46
+ cat .trellis/spec/frontend/index.md # Frontend guidelines
47
+ cat .trellis/spec/backend/index.md # Backend guidelines
48
+ cat .trellis/spec/guides/index.md # Thinking guides
49
+ ```
50
+
51
+ ### Step 4: Report and Ask
52
+
53
+ Report what you learned and ask: "What would you like to work on?"
54
+
55
+ ---
56
+
57
+ ## Task Classification
58
+
59
+ When user describes a task, classify it:
60
+
61
+ | Type | Criteria | Workflow |
62
+ |------|----------|----------|
63
+ | **Question** | User asks about code, architecture, or how something works | Answer directly |
64
+ | **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
65
+ | **Development Task** | Any code change that: modifies logic, adds features, fixes bugs, touches multiple files | **Task Workflow** |
66
+
67
+ ### Decision Rule
68
+
69
+ > **If in doubt, use Task Workflow.**
70
+ >
71
+ > Task Workflow ensures specs are injected to agents, resulting in higher quality code.
72
+ > The overhead is minimal, but the benefit is significant.
73
+
74
+ ---
75
+
76
+ ## Question / Trivial Fix
77
+
78
+ For questions or trivial fixes, work directly:
79
+
80
+ 1. Answer question or make the fix
81
+ 2. If code was changed, remind user to run `/trellis:finish-work`
82
+
83
+ ---
84
+
85
+ ## Task Workflow (Development Tasks)
86
+
87
+ **Why this workflow?**
88
+ - Research Agent analyzes what specs are needed
89
+ - Specs are configured in jsonl files
90
+ - Implement Agent receives specs via Hook injection
91
+ - Check Agent verifies against specs
92
+ - Result: Code that follows project conventions automatically
93
+
94
+ ### Overview: Two Entry Points
95
+
96
+ ```
97
+ From Brainstorm (Complex Task):
98
+ PRD confirmed -> Research -> Configure Context -> Activate -> Implement -> Check -> Complete
99
+
100
+ From Simple Task:
101
+ Confirm -> Create Task -> Write PRD -> Research -> Configure Context -> Activate -> Implement -> Check -> Complete
102
+ ```
103
+
104
+ **Key principle: Research happens AFTER requirements are clear (PRD exists).**
105
+
106
+ ---
107
+
108
+ ### Phase 1: Establish Requirements
109
+
110
+ #### Path A: From Brainstorm (skip to Phase 2)
111
+
112
+ PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
113
+
114
+ #### Path B: From Simple Task
115
+
116
+ **Step 1: Confirm Understanding** `[AI]`
117
+
118
+ Quick confirm:
119
+ - What is the goal?
120
+ - What type of development? (frontend / backend / fullstack)
121
+ - Any specific requirements or constraints?
122
+
123
+ **Step 2: Create Task Directory** `[AI]`
124
+
125
+ ```bash
126
+ TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
127
+ ```
128
+
129
+ **Step 3: Write PRD** `[AI]`
130
+
131
+ Create `prd.md` in the task directory with:
132
+
133
+ ```markdown
134
+ # <Task Title>
135
+
136
+ ## Goal
137
+ <What we're trying to achieve>
138
+
139
+ ## Requirements
140
+ - <Requirement 1>
141
+ - <Requirement 2>
142
+
143
+ ## Acceptance Criteria
144
+ - [ ] <Criterion 1>
145
+ - [ ] <Criterion 2>
146
+
147
+ ## Technical Notes
148
+ <Any technical decisions or constraints>
149
+ ```
150
+
151
+ ---
152
+
153
+ ### Phase 2: Prepare for Implementation (shared)
154
+
155
+ > Both paths converge here. PRD and task directory must exist before proceeding.
156
+
157
+ **Step 4: Code-Spec Depth Check** `[AI]`
158
+
159
+ If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
160
+
161
+ Trigger this requirement when the change includes any of:
162
+ - New or changed command/API signatures
163
+ - Database schema or migration changes
164
+ - Infra integrations (storage, queue, cache, secrets, env contracts)
165
+ - Cross-layer payload transformations
166
+
167
+ Must-have before proceeding:
168
+ - [ ] Target spec files to update are identified
169
+ - [ ] Concrete contract is defined (signature, fields, env keys)
170
+ - [ ] Validation and error matrix is defined
171
+ - [ ] At least one Good/Base/Bad case is defined
172
+
173
+ **Step 5: Research the Codebase** `[AI]`
174
+
175
+ Based on the confirmed PRD, run a focused research pass and produce:
176
+
177
+ 1. Relevant spec files in `.trellis/spec/`
178
+ 2. Existing code patterns to follow (2-3 examples)
179
+ 3. Files that will likely need modification
180
+
181
+ Use this output format:
182
+
183
+ ```markdown
184
+ ## Relevant Specs
185
+ - <path>: <why it's relevant>
186
+
187
+ ## Code Patterns Found
188
+ - <pattern>: <example file path>
189
+
190
+ ## Files to Modify
191
+ - <path>: <what change>
192
+ ```
193
+
194
+ **Step 6: Configure Context** `[AI]`
195
+
196
+ Initialize default context:
197
+
198
+ ```bash
199
+ python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
200
+ # type: backend | frontend | fullstack
201
+ ```
202
+
203
+ Add specs found in your research pass:
204
+
205
+ ```bash
206
+ # For each relevant spec and code pattern:
207
+ python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
208
+ python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
209
+ ```
210
+
211
+ **Step 7: Activate Task** `[AI]`
212
+
213
+ ```bash
214
+ python3 ./.trellis/scripts/task.py start "$TASK_DIR"
215
+ ```
216
+
217
+ This sets `.current-task` so hooks can inject context.
218
+
219
+ ---
220
+
221
+ ### Phase 3: Execute (shared)
222
+
223
+ **Step 8: Implement** `[AI]`
224
+
225
+ Implement the task described in `prd.md`.
226
+
227
+ - Follow all specs injected into implement context
228
+ - Keep changes scoped to requirements
229
+ - Run lint and typecheck before finishing
230
+
231
+ **Step 9: Check Quality** `[AI]`
232
+
233
+ Run a quality pass against check context:
234
+
235
+ - Review all code changes against the specs
236
+ - Fix issues directly
237
+ - Ensure lint and typecheck pass
238
+
239
+ **Step 10: Complete** `[AI]`
240
+
241
+ 1. Verify lint and typecheck pass
242
+ 2. Report what was implemented
243
+ 3. Remind user to:
244
+ - Test the changes
245
+ - Commit when ready
246
+ - Run `/trellis:record-session` to record this session
247
+
248
+ ---
249
+
250
+ ## Continuing Existing Task
251
+
252
+ If `get_context.py` shows a current task:
253
+
254
+ 1. Read the task's `prd.md` to understand the goal
255
+ 2. Check `task.json` for current status and phase
256
+ 3. Ask user: "Continue working on <task-name>?"
257
+
258
+ If yes, resume from the appropriate step (usually Step 7 or 8).
259
+
260
+ ---
261
+
262
+ ## Commands Reference
263
+
264
+ ### User Commands `[USER]`
265
+
266
+ | Command | When to Use |
267
+ |---------|-------------|
268
+ | `/trellis:start` | Begin a session (this command) |
269
+ | `/trellis:finish-work` | Before committing changes |
270
+ | `/trellis:record-session` | After completing a task |
271
+
272
+ ### AI Scripts `[AI]`
273
+
274
+ | Script | Purpose |
275
+ |--------|---------|
276
+ | `python3 ./.trellis/scripts/get_context.py` | Get session context |
277
+ | `python3 ./.trellis/scripts/task.py create` | Create task directory |
278
+ | `python3 ./.trellis/scripts/task.py init-context` | Initialize jsonl files |
279
+ | `python3 ./.trellis/scripts/task.py add-context` | Add spec to jsonl |
280
+ | `python3 ./.trellis/scripts/task.py start` | Set current task |
281
+ | `python3 ./.trellis/scripts/task.py finish` | Clear current task |
282
+ | `python3 ./.trellis/scripts/task.py archive` | Archive completed task |
283
+
284
+ ---
285
+
286
+ ## Key Principle
287
+
288
+ > **Specs are injected, not remembered.**
289
+ >
290
+ > The Task Workflow ensures agents receive relevant specs automatically.
291
+ > This is more reliable than hoping the AI "remembers" conventions.
292
+ """
@@ -0,0 +1,132 @@
1
+ description = "Capture knowledge into spec documents after learning something valuable"
2
+
3
+ prompt = """
4
+ # Update Spec - Capture Knowledge into Specifications
5
+
6
+ When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant spec documents.
7
+
8
+ **Timing**: After completing a task, fixing a bug, or discovering a new pattern
9
+
10
+ ---
11
+
12
+ ## When to Update Specs
13
+
14
+ | Trigger | Example | Target Spec |
15
+ |---------|---------|-------------|
16
+ | **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
17
+ | **Made a design decision** | Used type field + mapping table for extensibility | Relevant spec + "Design Decisions" section |
18
+ | **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
19
+ | **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
20
+ | **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
21
+ | **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
22
+ | **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
23
+
24
+ ---
25
+
26
+ ## Spec Structure Overview
27
+
28
+ ```
29
+ .trellis/spec/
30
+ +-- backend/ # Backend coding standards
31
+ | +-- index.md # Overview and links
32
+ | +-- *.md # Topic-specific guidelines
33
+ +-- frontend/ # Frontend coding standards
34
+ | +-- index.md # Overview and links
35
+ | +-- *.md # Topic-specific guidelines
36
+ +-- guides/ # Thinking checklists (NOT coding specs!)
37
+ +-- index.md # Guide index
38
+ +-- *.md # Topic-specific guides
39
+ ```
40
+
41
+ ### CRITICAL: Spec vs Guide - Know the Difference
42
+
43
+ | Type | Location | Purpose | Content Style |
44
+ |------|----------|---------|---------------|
45
+ | **Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to write code" | Detailed rules, code examples, forbidden patterns |
46
+ | **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
47
+
48
+ **Decision Rule**: Ask yourself:
49
+
50
+ - "This is **how to write** the code" -> Put in `backend/` or `frontend/`
51
+ - "This is **what to consider** before writing" -> Put in `guides/`
52
+
53
+ ---
54
+
55
+ ## Update Process
56
+
57
+ ### Step 1: Identify What You Learned
58
+
59
+ Answer these questions:
60
+
61
+ 1. **What did you learn?** (Be specific)
62
+ 2. **Why is it important?** (What problem does it prevent?)
63
+ 3. **Where does it belong?** (Which spec file?)
64
+
65
+ ### Step 2: Classify the Update Type
66
+
67
+ | Type | Description | Action |
68
+ |------|-------------|--------|
69
+ | **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
70
+ | **Project Convention** | How we do X in this project | Add to relevant section with examples |
71
+ | **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
72
+ | **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
73
+ | **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
74
+ | **Convention** | Agreed-upon standard | Add to relevant section |
75
+ | **Gotcha** | Non-obvious behavior | Add warning callout |
76
+
77
+ ### Step 3: Read the Target Spec
78
+
79
+ Before editing, read the current spec to:
80
+ - Understand existing structure
81
+ - Avoid duplicating content
82
+ - Find the right section for your update
83
+
84
+ ```bash
85
+ cat .trellis/spec/<category>/<file>.md
86
+ ```
87
+
88
+ ### Step 4: Make the Update
89
+
90
+ Follow these principles:
91
+
92
+ 1. **Be Specific**: Include concrete examples, not just abstract rules
93
+ 2. **Explain Why**: State the problem this prevents
94
+ 3. **Show Code**: Add code snippets for patterns
95
+ 4. **Keep it Short**: One concept per section
96
+
97
+ ### Step 5: Update the Index (if needed)
98
+
99
+ If you added a new section or the spec status changed, update the category's `index.md`.
100
+
101
+ ---
102
+
103
+ ## Quality Checklist
104
+
105
+ Before finishing your spec update:
106
+
107
+ - [ ] Is the content specific and actionable?
108
+ - [ ] Did you include a code example?
109
+ - [ ] Did you explain WHY, not just WHAT?
110
+ - [ ] Is it in the right spec file?
111
+ - [ ] Does it duplicate existing content?
112
+ - [ ] Would a new team member understand it?
113
+
114
+ ---
115
+
116
+ ## Relationship to Other Commands
117
+
118
+ - `/trellis:break-loop` - Analyzes bugs deeply, often reveals spec updates needed
119
+ - `/trellis:update-spec` - Actually makes the updates (this command)
120
+ - `/trellis:finish-work` - Reminds you to check if specs need updates
121
+
122
+ ---
123
+
124
+ ## Core Philosophy
125
+
126
+ > **Specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the spec better.**
127
+
128
+ The goal is **institutional memory**:
129
+ - What one person learns, everyone benefits from
130
+ - What AI learns in one session, persists to future sessions
131
+ - Mistakes become documented guardrails
132
+ """
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Gemini CLI templates
3
+ *
4
+ * These are GENERIC templates for user projects.
5
+ * Do NOT use Trellis project's own .gemini/ directory (which may be customized).
6
+ *
7
+ * Directory structure:
8
+ * gemini/
9
+ * └── commands/trellis/ # Slash commands (.toml files)
10
+ */
11
+ export interface CommandTemplate {
12
+ name: string;
13
+ content: string;
14
+ }
15
+ /**
16
+ * Get all command templates.
17
+ * Gemini CLI uses TOML format (.toml) instead of Markdown.
18
+ * Commands are in commands/trellis/ subdirectory for namespace.
19
+ */
20
+ export declare function getAllCommands(): CommandTemplate[];
21
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/gemini/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAqBH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,IAAI,eAAe,EAAE,CAalD"}
@@ -0,0 +1,44 @@
1
+ /**
2
+ * Gemini CLI templates
3
+ *
4
+ * These are GENERIC templates for user projects.
5
+ * Do NOT use Trellis project's own .gemini/ directory (which may be customized).
6
+ *
7
+ * Directory structure:
8
+ * gemini/
9
+ * └── commands/trellis/ # Slash commands (.toml files)
10
+ */
11
+ import { readdirSync, readFileSync } from "node:fs";
12
+ import { dirname, join } from "node:path";
13
+ import { fileURLToPath } from "node:url";
14
+ const __filename = fileURLToPath(import.meta.url);
15
+ const __dirname = dirname(__filename);
16
+ function readTemplate(relativePath) {
17
+ return readFileSync(join(__dirname, relativePath), "utf-8");
18
+ }
19
+ function listFiles(dir) {
20
+ try {
21
+ return readdirSync(join(__dirname, dir));
22
+ }
23
+ catch {
24
+ return [];
25
+ }
26
+ }
27
+ /**
28
+ * Get all command templates.
29
+ * Gemini CLI uses TOML format (.toml) instead of Markdown.
30
+ * Commands are in commands/trellis/ subdirectory for namespace.
31
+ */
32
+ export function getAllCommands() {
33
+ const commands = [];
34
+ const files = listFiles("commands/trellis");
35
+ for (const file of files) {
36
+ if (file.endsWith(".toml")) {
37
+ const name = file.replace(".toml", "");
38
+ const content = readTemplate(`commands/trellis/${file}`);
39
+ commands.push({ name, content });
40
+ }
41
+ }
42
+ return commands;
43
+ }
44
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/gemini/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,GAAW;IAC5B,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC;IAC3C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAOD;;;;GAIG;AACH,MAAM,UAAU,cAAc;IAC5B,MAAM,QAAQ,GAAsB,EAAE,CAAC;IACvC,MAAM,KAAK,GAAG,SAAS,CAAC,kBAAkB,CAAC,CAAC;IAE5C,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,YAAY,CAAC,oBAAoB,IAAI,EAAE,CAAC,CAAC;YACzD,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC"}
@@ -43,7 +43,7 @@ Read relevant specs based on task type:
43
43
 
44
44
  - Backend: `.trellis/spec/backend/`
45
45
  - Frontend: `.trellis/spec/frontend/`
46
- - Shared: `.trellis/spec/shared/`
46
+ - Guides: `.trellis/spec/guides/`
47
47
 
48
48
  ### 2. Understand Requirements
49
49