@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.
- package/README.md +16 -4
- package/dist/cli/index.js +4 -0
- package/dist/cli/index.js.map +1 -1
- package/dist/commands/init.d.ts +4 -0
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +29 -15
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +19 -11
- package/dist/commands/update.js.map +1 -1
- package/dist/configurators/antigravity.d.ts +8 -0
- package/dist/configurators/antigravity.d.ts.map +1 -0
- package/dist/configurators/antigravity.js +18 -0
- package/dist/configurators/antigravity.js.map +1 -0
- package/dist/configurators/gemini.d.ts +8 -0
- package/dist/configurators/gemini.d.ts.map +1 -0
- package/dist/configurators/gemini.js +52 -0
- package/dist/configurators/gemini.js.map +1 -0
- package/dist/configurators/index.d.ts.map +1 -1
- package/dist/configurators/index.js +49 -1
- package/dist/configurators/index.js.map +1 -1
- package/dist/configurators/kilo.d.ts +8 -0
- package/dist/configurators/kilo.d.ts.map +1 -0
- package/dist/configurators/kilo.js +51 -0
- package/dist/configurators/kilo.js.map +1 -0
- package/dist/configurators/kiro.d.ts +8 -0
- package/dist/configurators/kiro.d.ts.map +1 -0
- package/dist/configurators/kiro.js +20 -0
- package/dist/configurators/kiro.js.map +1 -0
- package/dist/migrations/manifests/0.3.0-rc.6.json +9 -0
- package/dist/migrations/manifests/0.3.0.json +11 -0
- package/dist/templates/antigravity/index.d.ts +12 -0
- package/dist/templates/antigravity/index.d.ts.map +1 -0
- package/dist/templates/antigravity/index.js +29 -0
- package/dist/templates/antigravity/index.js.map +1 -0
- package/dist/templates/claude/agents/implement.md +1 -1
- package/dist/templates/claude/commands/trellis/brainstorm.md +16 -18
- package/dist/templates/claude/commands/trellis/start.md +73 -48
- package/dist/templates/codex/skills/brainstorm/SKILL.md +16 -18
- package/dist/templates/codex/skills/start/SKILL.md +80 -46
- package/dist/templates/cursor/commands/trellis-brainstorm.md +16 -18
- package/dist/templates/cursor/commands/trellis-start.md +191 -23
- package/dist/templates/extract.d.ts +52 -0
- package/dist/templates/extract.d.ts.map +1 -1
- package/dist/templates/extract.js +90 -0
- package/dist/templates/extract.js.map +1 -1
- package/dist/templates/gemini/commands/trellis/before-backend-dev.toml +17 -0
- package/dist/templates/gemini/commands/trellis/before-frontend-dev.toml +17 -0
- package/dist/templates/gemini/commands/trellis/brainstorm.toml +420 -0
- package/dist/templates/gemini/commands/trellis/break-loop.toml +129 -0
- package/dist/templates/gemini/commands/trellis/check-backend.toml +17 -0
- package/dist/templates/gemini/commands/trellis/check-cross-layer.toml +147 -0
- package/dist/templates/gemini/commands/trellis/check-frontend.toml +17 -0
- package/dist/templates/gemini/commands/trellis/create-command.toml +119 -0
- package/dist/templates/gemini/commands/trellis/finish-work.toml +133 -0
- package/dist/templates/gemini/commands/trellis/integrate-skill.toml +104 -0
- package/dist/templates/gemini/commands/trellis/onboard.toml +111 -0
- package/dist/templates/gemini/commands/trellis/record-session.toml +66 -0
- package/dist/templates/gemini/commands/trellis/start.toml +292 -0
- package/dist/templates/gemini/commands/trellis/update-spec.toml +132 -0
- package/dist/templates/gemini/index.d.ts +21 -0
- package/dist/templates/gemini/index.d.ts.map +1 -0
- package/dist/templates/gemini/index.js +44 -0
- package/dist/templates/gemini/index.js.map +1 -0
- package/dist/templates/iflow/agents/implement.md +1 -1
- package/dist/templates/iflow/commands/trellis/brainstorm.md +16 -18
- package/dist/templates/iflow/commands/trellis/finish-work.md +9 -0
- package/dist/templates/iflow/commands/trellis/start.md +108 -50
- package/dist/templates/iflow/index.d.ts +3 -2
- package/dist/templates/iflow/index.d.ts.map +1 -1
- package/dist/templates/iflow/index.js +7 -9
- package/dist/templates/iflow/index.js.map +1 -1
- package/dist/templates/kilo/commands/trellis/before-backend-dev.md +13 -0
- package/dist/templates/kilo/commands/trellis/before-frontend-dev.md +13 -0
- package/dist/templates/kilo/commands/trellis/brainstorm.md +474 -0
- package/dist/templates/kilo/commands/trellis/break-loop.md +125 -0
- package/dist/templates/kilo/commands/trellis/check-backend.md +13 -0
- package/dist/templates/kilo/commands/trellis/check-cross-layer.md +153 -0
- package/dist/templates/kilo/commands/trellis/check-frontend.md +13 -0
- package/dist/templates/kilo/commands/trellis/create-command.md +152 -0
- package/dist/templates/kilo/commands/trellis/finish-work.md +129 -0
- package/dist/templates/kilo/commands/trellis/integrate-skill.md +219 -0
- package/dist/templates/kilo/commands/trellis/onboard.md +358 -0
- package/dist/templates/kilo/commands/trellis/parallel.md +194 -0
- package/dist/templates/kilo/commands/trellis/record-session.md +62 -0
- package/dist/templates/kilo/commands/trellis/start.md +321 -0
- package/dist/templates/kilo/commands/trellis/update-spec.md +285 -0
- package/dist/templates/kilo/index.d.ts +16 -0
- package/dist/templates/kilo/index.d.ts.map +1 -0
- package/dist/templates/kilo/index.js +39 -0
- package/dist/templates/kilo/index.js.map +1 -0
- package/dist/templates/kiro/index.d.ts +18 -0
- package/dist/templates/kiro/index.d.ts.map +1 -0
- package/dist/templates/kiro/index.js +40 -0
- package/dist/templates/kiro/index.js.map +1 -0
- package/dist/templates/kiro/skills/before-backend-dev/SKILL.md +18 -0
- package/dist/templates/kiro/skills/before-frontend-dev/SKILL.md +18 -0
- package/dist/templates/kiro/skills/brainstorm/SKILL.md +479 -0
- package/dist/templates/kiro/skills/break-loop/SKILL.md +130 -0
- package/dist/templates/kiro/skills/check-backend/SKILL.md +18 -0
- package/dist/templates/kiro/skills/check-cross-layer/SKILL.md +158 -0
- package/dist/templates/kiro/skills/check-frontend/SKILL.md +18 -0
- package/dist/templates/kiro/skills/create-command/SKILL.md +101 -0
- package/dist/templates/kiro/skills/finish-work/SKILL.md +148 -0
- package/dist/templates/kiro/skills/integrate-skill/SKILL.md +221 -0
- package/dist/templates/kiro/skills/onboard/SKILL.md +363 -0
- package/dist/templates/kiro/skills/record-session/SKILL.md +67 -0
- package/dist/templates/kiro/skills/start/SKILL.md +330 -0
- package/dist/templates/kiro/skills/update-spec/SKILL.md +335 -0
- package/dist/templates/opencode/agents/implement.md +1 -1
- package/dist/templates/opencode/agents/research.md +1 -2
- package/dist/templates/opencode/commands/trellis/brainstorm.md +16 -18
- package/dist/templates/opencode/commands/trellis/start.md +71 -48
- package/dist/templates/trellis/scripts/common/cli_adapter.py +100 -12
- package/dist/templates/trellis/scripts/common/registry.py +1 -1
- package/dist/templates/trellis/scripts/task.py +1 -8
- package/dist/types/ai-tools.d.ts +4 -4
- package/dist/types/ai-tools.d.ts.map +1 -1
- package/dist/types/ai-tools.js +32 -0
- package/dist/types/ai-tools.js.map +1 -1
- 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"}
|