@mindfoldhq/trellis 0.1.0 → 0.1.2
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 +58 -11
- package/dist/.claude/agents/check.md +98 -0
- package/dist/.claude/agents/debug.md +109 -0
- package/dist/{templates/agents/dispatch.txt → .claude/agents/dispatch.md} +20 -12
- package/dist/.claude/agents/implement.md +101 -0
- package/dist/.claude/agents/plan.md +396 -0
- package/dist/.claude/agents/research.md +120 -0
- package/dist/{templates/commands/common/check-cross-layer.txt → .claude/commands/check-cross-layer.md} +29 -29
- package/dist/{templates/commands/common/onboard-developer.txt → .claude/commands/onboard-developer.md} +2 -2
- package/dist/.claude/commands/parallel.md +199 -0
- package/dist/{templates/commands/common/record-agent-flow.txt → .claude/commands/record-agent-flow.md} +1 -1
- package/dist/.claude/commands/start.md +192 -0
- package/dist/{templates → .claude}/hooks/inject-subagent-context.py +63 -0
- package/dist/.cursor/commands/before-backend-dev.md +13 -0
- package/dist/.cursor/commands/before-frontend-dev.md +13 -0
- package/dist/.cursor/commands/break-loop.md +107 -0
- package/dist/.cursor/commands/check-backend.md +13 -0
- package/dist/.cursor/commands/check-cross-layer.md +153 -0
- package/dist/.cursor/commands/check-frontend.md +13 -0
- package/dist/.cursor/commands/create-command.md +154 -0
- package/dist/.cursor/commands/finish-work.md +129 -0
- package/dist/.cursor/commands/integrate-skill.md +219 -0
- package/dist/.cursor/commands/onboard-developer.md +355 -0
- package/dist/.cursor/commands/record-agent-flow.md +62 -0
- package/dist/.cursor/commands/start.md +157 -0
- package/dist/{templates/markdown/agent-traces-index.md.txt → .trellis/agent-traces/index.md} +8 -9
- package/dist/{templates/scripts/add-session.sh.txt → .trellis/scripts/add-session.sh} +14 -14
- package/dist/{templates/scripts/common/developer.sh.txt → .trellis/scripts/common/developer.sh} +13 -13
- package/dist/{templates/scripts/common/git-context.sh.txt → .trellis/scripts/common/git-context.sh} +8 -8
- package/dist/{templates/scripts/common/paths.sh.txt → .trellis/scripts/common/paths.sh} +4 -4
- package/dist/.trellis/scripts/common/phase.sh +150 -0
- package/dist/.trellis/scripts/common/worktree.sh +138 -0
- package/dist/{templates/scripts/feature.sh.txt → .trellis/scripts/feature.sh} +297 -0
- package/dist/.trellis/scripts/multi-agent/cleanup.sh +416 -0
- package/dist/.trellis/scripts/multi-agent/create-pr.sh +241 -0
- package/dist/.trellis/scripts/multi-agent/plan.sh +232 -0
- package/dist/.trellis/scripts/multi-agent/start.sh +344 -0
- package/dist/.trellis/scripts/multi-agent/status.sh +695 -0
- package/dist/.trellis/structure/backend/database-guidelines.md +51 -0
- package/dist/.trellis/structure/backend/directory-structure.md +209 -0
- package/dist/.trellis/structure/backend/error-handling.md +278 -0
- package/dist/.trellis/structure/backend/index.md +38 -0
- package/dist/.trellis/structure/backend/logging-guidelines.md +266 -0
- package/dist/.trellis/structure/backend/quality-guidelines.md +313 -0
- package/dist/.trellis/structure/frontend/component-guidelines.md +59 -0
- package/dist/.trellis/structure/frontend/directory-structure.md +54 -0
- package/dist/.trellis/structure/frontend/hook-guidelines.md +51 -0
- package/dist/.trellis/structure/frontend/index.md +39 -0
- package/dist/.trellis/structure/frontend/quality-guidelines.md +51 -0
- package/dist/.trellis/structure/frontend/state-management.md +51 -0
- package/dist/.trellis/structure/frontend/type-safety.md +51 -0
- package/dist/.trellis/structure/guides/code-reuse-thinking-guide.md +92 -0
- package/dist/.trellis/structure/guides/cross-layer-thinking-guide.md +94 -0
- package/dist/.trellis/structure/guides/index.md +79 -0
- package/dist/{templates/markdown/workflow.md.txt → .trellis/workflow.md} +6 -6
- package/dist/.trellis/worktree.yaml +49 -0
- package/dist/cli/index.js +1 -0
- package/dist/cli/index.js.map +1 -1
- 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/configurators/claude.d.ts +17 -17
- package/dist/configurators/claude.d.ts.map +1 -1
- package/dist/configurators/claude.js +29 -59
- package/dist/configurators/claude.js.map +1 -1
- package/dist/configurators/cursor.d.ts +3 -3
- package/dist/configurators/cursor.d.ts.map +1 -1
- package/dist/configurators/cursor.js +11 -15
- package/dist/configurators/cursor.js.map +1 -1
- package/dist/configurators/opencode.d.ts +25 -0
- package/dist/configurators/opencode.d.ts.map +1 -0
- package/dist/configurators/opencode.js +54 -0
- package/dist/configurators/opencode.js.map +1 -0
- package/dist/configurators/workflow.d.ts +9 -0
- package/dist/configurators/workflow.d.ts.map +1 -1
- package/dist/configurators/workflow.js +32 -72
- package/dist/configurators/workflow.js.map +1 -1
- package/dist/templates/extract.d.ts +73 -8
- package/dist/templates/extract.d.ts.map +1 -1
- package/dist/templates/extract.js +149 -10
- package/dist/templates/extract.js.map +1 -1
- package/dist/templates/markdown/{agents.md.txt → agents.md} +1 -1
- package/dist/templates/markdown/index.d.ts +5 -1
- package/dist/templates/markdown/index.d.ts.map +1 -1
- package/dist/templates/markdown/index.js +54 -26
- package/dist/templates/markdown/index.js.map +1 -1
- package/dist/templates/markdown/{init-agent.md.txt → init-agent.md} +8 -8
- package/dist/templates/markdown/structure/backend/directory-structure.md.txt +6 -6
- package/dist/templates/markdown/structure/backend/error-handling.md.txt +8 -8
- package/dist/templates/markdown/structure/backend/index.md.txt +5 -5
- package/dist/templates/markdown/structure/backend/logging-guidelines.md.txt +8 -8
- package/dist/templates/markdown/structure/frontend/index.md.txt +6 -6
- package/dist/templates/markdown/structure/guides/cross-layer-thinking-guide.md.txt +5 -5
- package/dist/templates/markdown/structure/guides/index.md.txt +7 -7
- package/dist/templates/markdown/worktree.yaml.txt +58 -0
- package/dist/types/ai-tools.d.ts +2 -2
- package/dist/types/ai-tools.d.ts.map +1 -1
- package/dist/types/ai-tools.js +4 -0
- package/dist/types/ai-tools.js.map +1 -1
- package/package.json +1 -1
- package/dist/configurators/templates.d.ts +0 -40
- package/dist/configurators/templates.d.ts.map +0 -1
- package/dist/configurators/templates.js +0 -67
- package/dist/configurators/templates.js.map +0 -1
- package/dist/templates/agents/check.txt +0 -120
- package/dist/templates/agents/debug.txt +0 -121
- package/dist/templates/agents/implement.txt +0 -114
- package/dist/templates/agents/index.d.ts +0 -35
- package/dist/templates/agents/index.d.ts.map +0 -1
- package/dist/templates/agents/index.js +0 -71
- package/dist/templates/agents/index.js.map +0 -1
- package/dist/templates/agents/research.txt +0 -258
- package/dist/templates/commands/claude/start.md.txt +0 -127
- package/dist/templates/commands/cursor/start.md.txt +0 -94
- package/dist/templates/commands/index.d.ts +0 -46
- package/dist/templates/commands/index.d.ts.map +0 -1
- package/dist/templates/commands/index.js +0 -151
- package/dist/templates/commands/index.js.map +0 -1
- package/dist/templates/hooks/index.d.ts +0 -33
- package/dist/templates/hooks/index.d.ts.map +0 -1
- package/dist/templates/hooks/index.js +0 -53
- package/dist/templates/hooks/index.js.map +0 -1
- package/dist/templates/markdown/gitignore.txt +0 -3
- package/dist/templates/scripts/index.d.ts +0 -25
- package/dist/templates/scripts/index.d.ts.map +0 -1
- package/dist/templates/scripts/index.js +0 -28
- package/dist/templates/scripts/index.js.map +0 -1
- /package/dist/{templates/commands/common/before-backend-dev.txt → .claude/commands/before-backend-dev.md} +0 -0
- /package/dist/{templates/commands/common/before-frontend-dev.txt → .claude/commands/before-frontend-dev.md} +0 -0
- /package/dist/{templates/commands/common/break-loop.txt → .claude/commands/break-loop.md} +0 -0
- /package/dist/{templates/commands/common/check-backend.txt → .claude/commands/check-backend.md} +0 -0
- /package/dist/{templates/commands/common/check-frontend.txt → .claude/commands/check-frontend.md} +0 -0
- /package/dist/{templates/commands/common/create-command.txt → .claude/commands/create-command.md} +0 -0
- /package/dist/{templates/commands/common/finish-work.txt → .claude/commands/finish-work.md} +0 -0
- /package/dist/{templates/commands/common/integrate-skill.txt → .claude/commands/integrate-skill.md} +0 -0
- /package/dist/{templates/hooks → .claude}/settings.json +0 -0
- /package/dist/{templates/scripts/create-bootstrap.sh.txt → .trellis/scripts/create-bootstrap.sh} +0 -0
- /package/dist/{templates/scripts/get-context.sh.txt → .trellis/scripts/get-context.sh} +0 -0
- /package/dist/{templates/scripts/get-developer.sh.txt → .trellis/scripts/get-developer.sh} +0 -0
- /package/dist/{templates/scripts/init-developer.sh.txt → .trellis/scripts/init-developer.sh} +0 -0
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Hook Guidelines
|
|
2
|
+
|
|
3
|
+
> How hooks are used in this project.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
Document your project's hook conventions here.
|
|
11
|
+
|
|
12
|
+
Questions to answer:
|
|
13
|
+
- What custom hooks do you have?
|
|
14
|
+
- How do you handle data fetching?
|
|
15
|
+
- What are the naming conventions?
|
|
16
|
+
- How do you share stateful logic?
|
|
17
|
+
-->
|
|
18
|
+
|
|
19
|
+
(To be filled by the team)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Custom Hook Patterns
|
|
24
|
+
|
|
25
|
+
<!-- How to create and structure custom hooks -->
|
|
26
|
+
|
|
27
|
+
(To be filled by the team)
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Data Fetching
|
|
32
|
+
|
|
33
|
+
<!-- How data fetching is handled (React Query, SWR, etc.) -->
|
|
34
|
+
|
|
35
|
+
(To be filled by the team)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Naming Conventions
|
|
40
|
+
|
|
41
|
+
<!-- Hook naming rules (use*, etc.) -->
|
|
42
|
+
|
|
43
|
+
(To be filled by the team)
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Common Mistakes
|
|
48
|
+
|
|
49
|
+
<!-- Hook-related mistakes your team has made -->
|
|
50
|
+
|
|
51
|
+
(To be filled by the team)
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Frontend Development Guidelines
|
|
2
|
+
|
|
3
|
+
> Best practices for frontend development in this project.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Guidelines Index
|
|
14
|
+
|
|
15
|
+
| Guide | Description | Status |
|
|
16
|
+
|-------|-------------|--------|
|
|
17
|
+
| [Directory Structure](./directory-structure.md) | Module organization and file layout | ⬜ To fill |
|
|
18
|
+
| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | ⬜ To fill |
|
|
19
|
+
| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | ⬜ To fill |
|
|
20
|
+
| [State Management](./state-management.md) | Local state, global state, server state | ⬜ To fill |
|
|
21
|
+
| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | ⬜ To fill |
|
|
22
|
+
| [Type Safety](./type-safety.md) | Type patterns, validation | ⬜ To fill |
|
|
23
|
+
|
|
24
|
+
---
|
|
25
|
+
|
|
26
|
+
## How to Fill These Guidelines
|
|
27
|
+
|
|
28
|
+
For each guideline file:
|
|
29
|
+
|
|
30
|
+
1. Document your project's **actual conventions** (not ideals)
|
|
31
|
+
2. Include **code examples** from your codebase
|
|
32
|
+
3. List **forbidden patterns** and why
|
|
33
|
+
4. Add **common mistakes** your team has made
|
|
34
|
+
|
|
35
|
+
The goal is to help AI assistants and new team members understand how YOUR project works.
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
**Language**: All documentation should be written in **English**.
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Quality Guidelines
|
|
2
|
+
|
|
3
|
+
> Code quality standards for frontend development.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
Document your project's quality standards here.
|
|
11
|
+
|
|
12
|
+
Questions to answer:
|
|
13
|
+
- What patterns are forbidden?
|
|
14
|
+
- What linting rules do you enforce?
|
|
15
|
+
- What are your testing requirements?
|
|
16
|
+
- What code review standards apply?
|
|
17
|
+
-->
|
|
18
|
+
|
|
19
|
+
(To be filled by the team)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Forbidden Patterns
|
|
24
|
+
|
|
25
|
+
<!-- Patterns that should never be used and why -->
|
|
26
|
+
|
|
27
|
+
(To be filled by the team)
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Required Patterns
|
|
32
|
+
|
|
33
|
+
<!-- Patterns that must always be used -->
|
|
34
|
+
|
|
35
|
+
(To be filled by the team)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Testing Requirements
|
|
40
|
+
|
|
41
|
+
<!-- What level of testing is expected -->
|
|
42
|
+
|
|
43
|
+
(To be filled by the team)
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Code Review Checklist
|
|
48
|
+
|
|
49
|
+
<!-- What reviewers should check -->
|
|
50
|
+
|
|
51
|
+
(To be filled by the team)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# State Management
|
|
2
|
+
|
|
3
|
+
> How state is managed in this project.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
Document your project's state management conventions here.
|
|
11
|
+
|
|
12
|
+
Questions to answer:
|
|
13
|
+
- What state management solution do you use?
|
|
14
|
+
- How is local vs global state decided?
|
|
15
|
+
- How do you handle server state?
|
|
16
|
+
- What are the patterns for derived state?
|
|
17
|
+
-->
|
|
18
|
+
|
|
19
|
+
(To be filled by the team)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## State Categories
|
|
24
|
+
|
|
25
|
+
<!-- Local state, global state, server state, URL state -->
|
|
26
|
+
|
|
27
|
+
(To be filled by the team)
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## When to Use Global State
|
|
32
|
+
|
|
33
|
+
<!-- Criteria for promoting state to global -->
|
|
34
|
+
|
|
35
|
+
(To be filled by the team)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Server State
|
|
40
|
+
|
|
41
|
+
<!-- How server data is cached and synchronized -->
|
|
42
|
+
|
|
43
|
+
(To be filled by the team)
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Common Mistakes
|
|
48
|
+
|
|
49
|
+
<!-- State management mistakes your team has made -->
|
|
50
|
+
|
|
51
|
+
(To be filled by the team)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Type Safety
|
|
2
|
+
|
|
3
|
+
> Type safety patterns in this project.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Overview
|
|
8
|
+
|
|
9
|
+
<!--
|
|
10
|
+
Document your project's type safety conventions here.
|
|
11
|
+
|
|
12
|
+
Questions to answer:
|
|
13
|
+
- What type system do you use?
|
|
14
|
+
- How are types organized?
|
|
15
|
+
- What validation library do you use?
|
|
16
|
+
- How do you handle type inference?
|
|
17
|
+
-->
|
|
18
|
+
|
|
19
|
+
(To be filled by the team)
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Type Organization
|
|
24
|
+
|
|
25
|
+
<!-- Where types are defined, shared types vs local types -->
|
|
26
|
+
|
|
27
|
+
(To be filled by the team)
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Validation
|
|
32
|
+
|
|
33
|
+
<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
|
|
34
|
+
|
|
35
|
+
(To be filled by the team)
|
|
36
|
+
|
|
37
|
+
---
|
|
38
|
+
|
|
39
|
+
## Common Patterns
|
|
40
|
+
|
|
41
|
+
<!-- Type utilities, generics, type guards -->
|
|
42
|
+
|
|
43
|
+
(To be filled by the team)
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Forbidden Patterns
|
|
48
|
+
|
|
49
|
+
<!-- any, type assertions, etc. -->
|
|
50
|
+
|
|
51
|
+
(To be filled by the team)
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# Code Reuse Thinking Guide
|
|
2
|
+
|
|
3
|
+
> **Purpose**: Stop and think before creating new code - does it already exist?
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## The Problem
|
|
8
|
+
|
|
9
|
+
**Duplicated code is the #1 source of inconsistency bugs.**
|
|
10
|
+
|
|
11
|
+
When you copy-paste or rewrite existing logic:
|
|
12
|
+
- Bug fixes don't propagate
|
|
13
|
+
- Behavior diverges over time
|
|
14
|
+
- Codebase becomes harder to understand
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Before Writing New Code
|
|
19
|
+
|
|
20
|
+
### Step 1: Search First
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
# Search for similar function names
|
|
24
|
+
grep -r "functionName" .
|
|
25
|
+
|
|
26
|
+
# Search for similar logic
|
|
27
|
+
grep -r "keyword" .
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Step 2: Ask These Questions
|
|
31
|
+
|
|
32
|
+
| Question | If Yes... |
|
|
33
|
+
|----------|-----------|
|
|
34
|
+
| Does a similar function exist? | Use or extend it |
|
|
35
|
+
| Is this pattern used elsewhere? | Follow the existing pattern |
|
|
36
|
+
| Could this be a shared utility? | Create it in the right place |
|
|
37
|
+
| Am I copying code from another file? | **STOP** - extract to shared |
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## Common Duplication Patterns
|
|
42
|
+
|
|
43
|
+
### Pattern 1: Copy-Paste Functions
|
|
44
|
+
|
|
45
|
+
**Bad**: Copying a validation function to another file
|
|
46
|
+
|
|
47
|
+
**Good**: Extract to shared utilities, import where needed
|
|
48
|
+
|
|
49
|
+
### Pattern 2: Similar Components
|
|
50
|
+
|
|
51
|
+
**Bad**: Creating a new component that's 80% similar to existing
|
|
52
|
+
|
|
53
|
+
**Good**: Extend existing component with props/variants
|
|
54
|
+
|
|
55
|
+
### Pattern 3: Repeated Constants
|
|
56
|
+
|
|
57
|
+
**Bad**: Defining the same constant in multiple files
|
|
58
|
+
|
|
59
|
+
**Good**: Single source of truth, import everywhere
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## When to Abstract
|
|
64
|
+
|
|
65
|
+
**Abstract when**:
|
|
66
|
+
- Same code appears 3+ times
|
|
67
|
+
- Logic is complex enough to have bugs
|
|
68
|
+
- Multiple people might need this
|
|
69
|
+
|
|
70
|
+
**Don't abstract when**:
|
|
71
|
+
- Only used once
|
|
72
|
+
- Trivial one-liner
|
|
73
|
+
- Abstraction would be more complex than duplication
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
## After Batch Modifications
|
|
78
|
+
|
|
79
|
+
When you've made similar changes to multiple files:
|
|
80
|
+
|
|
81
|
+
1. **Review**: Did you catch all instances?
|
|
82
|
+
2. **Search**: Run grep to find any missed
|
|
83
|
+
3. **Consider**: Should this be abstracted?
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
## Checklist Before Commit
|
|
88
|
+
|
|
89
|
+
- [ ] Searched for existing similar code
|
|
90
|
+
- [ ] No copy-pasted logic that should be shared
|
|
91
|
+
- [ ] Constants defined in one place
|
|
92
|
+
- [ ] Similar patterns follow same structure
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# Cross-Layer Thinking Guide
|
|
2
|
+
|
|
3
|
+
> **Purpose**: Think through data flow across layers before implementing.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## The Problem
|
|
8
|
+
|
|
9
|
+
**Most bugs happen at layer boundaries**, not within layers.
|
|
10
|
+
|
|
11
|
+
Common cross-layer bugs:
|
|
12
|
+
- API returns format A, frontend expects format B
|
|
13
|
+
- Database stores X, service transforms to Y, but loses data
|
|
14
|
+
- Multiple layers implement the same logic differently
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## Before Implementing Cross-Layer Features
|
|
19
|
+
|
|
20
|
+
### Step 1: Map the Data Flow
|
|
21
|
+
|
|
22
|
+
Draw out how data moves:
|
|
23
|
+
|
|
24
|
+
```
|
|
25
|
+
Source → Transform → Store → Retrieve → Transform → Display
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
For each arrow, ask:
|
|
29
|
+
- What format is the data in?
|
|
30
|
+
- What could go wrong?
|
|
31
|
+
- Who is responsible for validation?
|
|
32
|
+
|
|
33
|
+
### Step 2: Identify Boundaries
|
|
34
|
+
|
|
35
|
+
| Boundary | Common Issues |
|
|
36
|
+
|----------|---------------|
|
|
37
|
+
| API ↔ Service | Type mismatches, missing fields |
|
|
38
|
+
| Service ↔ Database | Format conversions, null handling |
|
|
39
|
+
| Backend ↔ Frontend | Serialization, date formats |
|
|
40
|
+
| Component ↔ Component | Props shape changes |
|
|
41
|
+
|
|
42
|
+
### Step 3: Define Contracts
|
|
43
|
+
|
|
44
|
+
For each boundary:
|
|
45
|
+
- What is the exact input format?
|
|
46
|
+
- What is the exact output format?
|
|
47
|
+
- What errors can occur?
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Common Cross-Layer Mistakes
|
|
52
|
+
|
|
53
|
+
### Mistake 1: Implicit Format Assumptions
|
|
54
|
+
|
|
55
|
+
**Bad**: Assuming date format without checking
|
|
56
|
+
|
|
57
|
+
**Good**: Explicit format conversion at boundaries
|
|
58
|
+
|
|
59
|
+
### Mistake 2: Scattered Validation
|
|
60
|
+
|
|
61
|
+
**Bad**: Validating the same thing in multiple layers
|
|
62
|
+
|
|
63
|
+
**Good**: Validate once at the entry point
|
|
64
|
+
|
|
65
|
+
### Mistake 3: Leaky Abstractions
|
|
66
|
+
|
|
67
|
+
**Bad**: Component knows about database schema
|
|
68
|
+
|
|
69
|
+
**Good**: Each layer only knows its neighbors
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Checklist for Cross-Layer Features
|
|
74
|
+
|
|
75
|
+
Before implementation:
|
|
76
|
+
- [ ] Mapped the complete data flow
|
|
77
|
+
- [ ] Identified all layer boundaries
|
|
78
|
+
- [ ] Defined format at each boundary
|
|
79
|
+
- [ ] Decided where validation happens
|
|
80
|
+
|
|
81
|
+
After implementation:
|
|
82
|
+
- [ ] Tested with edge cases (null, empty, invalid)
|
|
83
|
+
- [ ] Verified error handling at each boundary
|
|
84
|
+
- [ ] Checked data survives round-trip
|
|
85
|
+
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## When to Create Flow Documentation
|
|
89
|
+
|
|
90
|
+
Create detailed flow docs when:
|
|
91
|
+
- Feature spans 3+ layers
|
|
92
|
+
- Multiple teams are involved
|
|
93
|
+
- Data format is complex
|
|
94
|
+
- Feature has caused bugs before
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# Thinking Guides
|
|
2
|
+
|
|
3
|
+
> **Purpose**: Expand your thinking to catch things you might not have considered.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Why Thinking Guides?
|
|
8
|
+
|
|
9
|
+
**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
|
|
10
|
+
|
|
11
|
+
- Didn't think about what happens at layer boundaries → cross-layer bugs
|
|
12
|
+
- Didn't think about code patterns repeating → duplicated code everywhere
|
|
13
|
+
- Didn't think about edge cases → runtime errors
|
|
14
|
+
- Didn't think about future maintainers → unreadable code
|
|
15
|
+
|
|
16
|
+
These guides help you **ask the right questions before coding**.
|
|
17
|
+
|
|
18
|
+
---
|
|
19
|
+
|
|
20
|
+
## Available Guides
|
|
21
|
+
|
|
22
|
+
| Guide | Purpose | When to Use |
|
|
23
|
+
|-------|---------|-------------|
|
|
24
|
+
| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
|
|
25
|
+
| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Quick Reference: Thinking Triggers
|
|
30
|
+
|
|
31
|
+
### When to Think About Cross-Layer Issues
|
|
32
|
+
|
|
33
|
+
- [ ] Feature touches 3+ layers (API, Service, Component, Database)
|
|
34
|
+
- [ ] Data format changes between layers
|
|
35
|
+
- [ ] Multiple consumers need the same data
|
|
36
|
+
- [ ] You're not sure where to put some logic
|
|
37
|
+
|
|
38
|
+
→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
|
|
39
|
+
|
|
40
|
+
### When to Think About Code Reuse
|
|
41
|
+
|
|
42
|
+
- [ ] You're writing similar code to something that exists
|
|
43
|
+
- [ ] You see the same pattern repeated 3+ times
|
|
44
|
+
- [ ] You're adding a new field to multiple places
|
|
45
|
+
- [ ] **You're modifying any constant or config**
|
|
46
|
+
- [ ] **You're creating a new utility/helper function** ← Search first!
|
|
47
|
+
|
|
48
|
+
→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## Pre-Modification Rule (CRITICAL)
|
|
53
|
+
|
|
54
|
+
> **Before changing ANY value, ALWAYS search first!**
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
# Search for the value you're about to change
|
|
58
|
+
grep -r "value_to_change" .
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This single habit prevents most "forgot to update X" bugs.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## How to Use This Directory
|
|
66
|
+
|
|
67
|
+
1. **Before coding**: Skim the relevant thinking guide
|
|
68
|
+
2. **During coding**: If something feels repetitive or complex, check the guides
|
|
69
|
+
3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Contributing
|
|
74
|
+
|
|
75
|
+
Found a new "didn't think of that" moment? Add it to the relevant guide.
|
|
76
|
+
|
|
77
|
+
---
|
|
78
|
+
|
|
79
|
+
**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
|
|
@@ -40,14 +40,14 @@
|
|
|
40
40
|
| |-- feature.sh # Manage features
|
|
41
41
|
| |-- get-context.sh # Get session context
|
|
42
42
|
| \-- add-session.sh # One-click session recording
|
|
43
|
-
|-- agent-traces/ # AI Agent work
|
|
44
|
-
| |-- index.md #
|
|
43
|
+
|-- agent-traces/ # AI Agent work traces records
|
|
44
|
+
| |-- index.md # Traces index + Session template
|
|
45
45
|
| \-- {developer}/ # Per-developer directories
|
|
46
46
|
| |-- index.md # Personal index (with @@@auto markers)
|
|
47
47
|
| |-- features/ # Feature directories
|
|
48
48
|
| | \-- {day}-{name}/
|
|
49
49
|
| | \-- feature.json
|
|
50
|
-
| \--
|
|
50
|
+
| \-- traces-N.md # Traces files (sequential numbering)
|
|
51
51
|
|-- structure/ # [!] MUST READ before coding
|
|
52
52
|
| |-- frontend/ # Frontend guidelines (if applicable)
|
|
53
53
|
| | |-- index.md # Start here - guidelines index
|
|
@@ -168,7 +168,7 @@ After code is committed, use:
|
|
|
168
168
|
```
|
|
169
169
|
|
|
170
170
|
This automatically:
|
|
171
|
-
1. Detects current
|
|
171
|
+
1. Detects current traces file
|
|
172
172
|
2. Creates new file if 2000-line limit exceeded
|
|
173
173
|
3. Appends session content
|
|
174
174
|
4. Updates index.md (sessions count, history table)
|
|
@@ -186,7 +186,7 @@ Use `/finish-work` command to run through:
|
|
|
186
186
|
|
|
187
187
|
## File Descriptions
|
|
188
188
|
|
|
189
|
-
### 1. agent-traces/ - Agent Work
|
|
189
|
+
### 1. agent-traces/ - Agent Work Traces
|
|
190
190
|
|
|
191
191
|
**Purpose**: Record each AI Agent session's work content
|
|
192
192
|
|
|
@@ -199,7 +199,7 @@ agent-traces/
|
|
|
199
199
|
|-- features/ # Feature directories
|
|
200
200
|
| \-- {day}-{name}/ # Each feature is a directory
|
|
201
201
|
| \-- feature.json
|
|
202
|
-
\--
|
|
202
|
+
\-- traces-N.md # Traces files (sequential: 1, 2, 3...)
|
|
203
203
|
```
|
|
204
204
|
|
|
205
205
|
**When to update**:
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# Worktree Configuration for Multi-Agent Pipeline
|
|
2
|
+
# Used for worktree initialization in multi-agent workflows
|
|
3
|
+
#
|
|
4
|
+
# All paths are relative to project root
|
|
5
|
+
|
|
6
|
+
#-------------------------------------------------------------------------------
|
|
7
|
+
# Paths
|
|
8
|
+
#-------------------------------------------------------------------------------
|
|
9
|
+
|
|
10
|
+
# Worktree storage directory (relative to project root)
|
|
11
|
+
worktree_dir: ../trellis-worktrees
|
|
12
|
+
|
|
13
|
+
#-------------------------------------------------------------------------------
|
|
14
|
+
# Files to Copy
|
|
15
|
+
#-------------------------------------------------------------------------------
|
|
16
|
+
|
|
17
|
+
# Files to copy to each worktree (each worktree needs independent copy)
|
|
18
|
+
# These files contain sensitive info or need worktree-independent config
|
|
19
|
+
copy:
|
|
20
|
+
# Environment variables (uncomment and customize as needed)
|
|
21
|
+
# - .env
|
|
22
|
+
# - .env.local
|
|
23
|
+
# Workflow config
|
|
24
|
+
- .trellis/.developer
|
|
25
|
+
|
|
26
|
+
#-------------------------------------------------------------------------------
|
|
27
|
+
# Post-Create Hooks
|
|
28
|
+
#-------------------------------------------------------------------------------
|
|
29
|
+
|
|
30
|
+
# Commands to run after creating worktree
|
|
31
|
+
# Executed in worktree directory, in order, abort on failure
|
|
32
|
+
post_create:
|
|
33
|
+
# Install dependencies (uncomment based on your package manager)
|
|
34
|
+
# - npm install
|
|
35
|
+
# - pnpm install --frozen-lockfile
|
|
36
|
+
# - yarn install --frozen-lockfile
|
|
37
|
+
|
|
38
|
+
#-------------------------------------------------------------------------------
|
|
39
|
+
# Pre-Merge Checks
|
|
40
|
+
#-------------------------------------------------------------------------------
|
|
41
|
+
|
|
42
|
+
# Pre-merge validation (used by create-pr.sh)
|
|
43
|
+
pre_merge:
|
|
44
|
+
# Type checking (uncomment based on your setup)
|
|
45
|
+
# - npm run typecheck
|
|
46
|
+
# - pnpm typecheck
|
|
47
|
+
# Linting
|
|
48
|
+
# - npm run lint
|
|
49
|
+
# - pnpm lint
|
package/dist/cli/index.js
CHANGED
|
@@ -19,6 +19,7 @@ program
|
|
|
19
19
|
.description("Initialize trellis in the current project")
|
|
20
20
|
.option("--cursor", "Include Cursor commands")
|
|
21
21
|
.option("--claude", "Include Claude Code commands")
|
|
22
|
+
// .option("--opencode", "Include OpenCode commands") // TODO: Re-enable when OpenCode support is stable
|
|
22
23
|
.option("-y, --yes", "Skip prompts and use defaults")
|
|
23
24
|
.option("-u, --user <name>", "Initialize developer identity with specified name")
|
|
24
25
|
.option("-f, --force", "Overwrite existing files without asking")
|
package/dist/cli/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAM3C,iCAAiC;AACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;AACtE,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CACzC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAC1C,CAAC;AACF,MAAM,CAAC,MAAM,OAAO,GAAW,WAAW,CAAC,OAAO,CAAC;AAEnD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CACV,6EAA6E,CAC9E;KACA,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,2BAA2B,CAAC,CAAC;AAElE,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,UAAU,EAAE,yBAAyB,CAAC;KAC7C,MAAM,CAAC,UAAU,EAAE,8BAA8B,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,qBAAqB,CAAC;AAM3C,iCAAiC;AACjC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC/D,MAAM,eAAe,GAAG,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,oBAAoB,CAAC,CAAC;AACtE,MAAM,WAAW,GAAgB,IAAI,CAAC,KAAK,CACzC,EAAE,CAAC,YAAY,CAAC,eAAe,EAAE,OAAO,CAAC,CAC1C,CAAC;AACF,MAAM,CAAC,MAAM,OAAO,GAAW,WAAW,CAAC,OAAO,CAAC;AAEnD,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;AAE9B,OAAO;KACJ,IAAI,CAAC,SAAS,CAAC;KACf,WAAW,CACV,6EAA6E,CAC9E;KACA,OAAO,CAAC,OAAO,EAAE,eAAe,EAAE,2BAA2B,CAAC,CAAC;AAElE,OAAO;KACJ,OAAO,CAAC,MAAM,CAAC;KACf,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,UAAU,EAAE,yBAAyB,CAAC;KAC7C,MAAM,CAAC,UAAU,EAAE,8BAA8B,CAAC;IACnD,yGAAyG;KACxG,MAAM,CAAC,WAAW,EAAE,+BAA+B,CAAC;KACpD,MAAM,CACL,mBAAmB,EACnB,mDAAmD,CACpD;KACA,MAAM,CAAC,aAAa,EAAE,yCAAyC,CAAC;KAChE,MAAM,CAAC,qBAAqB,EAAE,oCAAoC,CAAC;KACnE,MAAM,CAAC,KAAK,EAAE,OAAgC,EAAE,EAAE;IACjD,IAAI,CAAC;QACH,MAAM,IAAI,CAAC,OAAO,CAAC,CAAC;IACtB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,EACnB,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC,CAAC,CAAC;AAEL,OAAO;KACJ,OAAO,CAAC,QAAQ,CAAC;KACjB,WAAW,CAAC,2CAA2C,CAAC;KACxD,MAAM,CAAC,GAAG,EAAE;IACX,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,6BAA6B,CAAC,CAAC,CAAC;AAC3D,CAAC,CAAC,CAAC;AAEL,OAAO,CAAC,KAAK,EAAE,CAAC"}
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AA+BA,UAAU,WAAW;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAMD,wBAAsB,IAAI,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA2Q9D"}
|