@blulotus/trellis 0.7.0

package/dist/templates/markdown/spec/frontend/directory-structure.md.txt

@@ -0,0 +1,54 @@
+# Directory Structure
+
+> How frontend code is organized in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's frontend directory structure here.
+
+Questions to answer:
+- Where do components live?
+- How are features/modules organized?
+- Where are shared utilities?
+- How are assets organized?
+-->
+
+(To be filled by the team)
+
+---
+
+## Directory Layout
+
+```
+<!-- Replace with your actual structure -->
+src/
+├── ...
+└── ...
+```
+
+---
+
+## Module Organization
+
+<!-- How should new features be organized? -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- File and folder naming rules -->
+
+(To be filled by the team)
+
+---
+
+## Examples
+
+<!-- Link to well-organized modules as examples -->
+
+(To be filled by the team)

package/dist/templates/markdown/spec/frontend/hook-guidelines.md.txt

@@ -0,0 +1,51 @@
+# Hook Guidelines
+
+> How hooks are used in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's hook conventions here.
+
+Questions to answer:
+- What custom hooks do you have?
+- How do you handle data fetching?
+- What are the naming conventions?
+- How do you share stateful logic?
+-->
+
+(To be filled by the team)
+
+---
+
+## Custom Hook Patterns
+
+<!-- How to create and structure custom hooks -->
+
+(To be filled by the team)
+
+---
+
+## Data Fetching
+
+<!-- How data fetching is handled (React Query, SWR, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Naming Conventions
+
+<!-- Hook naming rules (use*, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Hook-related mistakes your team has made -->
+
+(To be filled by the team)

package/dist/templates/markdown/spec/frontend/index.md.txt

@@ -0,0 +1,39 @@
+# Frontend Development Guidelines
+
+> Best practices for frontend development in this project.
+
+---
+
+## Overview
+
+This directory contains guidelines for frontend development. Fill in each file with your project's specific conventions.
+
+---
+
+## Guidelines Index
+
+| Guide | Description | Status |
+|-------|-------------|--------|
+| [Directory Structure](./directory-structure.md) | Module organization and file layout | To fill |
+| [Component Guidelines](./component-guidelines.md) | Component patterns, props, composition | To fill |
+| [Hook Guidelines](./hook-guidelines.md) | Custom hooks, data fetching patterns | To fill |
+| [State Management](./state-management.md) | Local state, global state, server state | To fill |
+| [Quality Guidelines](./quality-guidelines.md) | Code standards, forbidden patterns | To fill |
+| [Type Safety](./type-safety.md) | Type patterns, validation | To fill |
+
+---
+
+## How to Fill These Guidelines
+
+For each guideline file:
+
+1. Document your project's **actual conventions** (not ideals)
+2. Include **code examples** from your codebase
+3. List **forbidden patterns** and why
+4. Add **common mistakes** your team has made
+
+The goal is to help AI assistants and new team members understand how YOUR project works.
+
+---
+
+**Language**: All documentation should be written in **English**.

package/dist/templates/markdown/spec/frontend/quality-guidelines.md.txt

@@ -0,0 +1,51 @@
+# Quality Guidelines
+
+> Code quality standards for frontend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+(To be filled by the team)
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

package/dist/templates/markdown/spec/frontend/state-management.md.txt

@@ -0,0 +1,51 @@
+# State Management
+
+> How state is managed in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's state management conventions here.
+
+Questions to answer:
+- What state management solution do you use?
+- How is local vs global state decided?
+- How do you handle server state?
+- What are the patterns for derived state?
+-->
+
+(To be filled by the team)
+
+---
+
+## State Categories
+
+<!-- Local state, global state, server state, URL state -->
+
+(To be filled by the team)
+
+---
+
+## When to Use Global State
+
+<!-- Criteria for promoting state to global -->
+
+(To be filled by the team)
+
+---
+
+## Server State
+
+<!-- How server data is cached and synchronized -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- State management mistakes your team has made -->
+
+(To be filled by the team)

package/dist/templates/markdown/spec/frontend/type-safety.md.txt

@@ -0,0 +1,51 @@
+# Type Safety
+
+> Type safety patterns in this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's type safety conventions here.
+
+Questions to answer:
+- What type system do you use?
+- How are types organized?
+- What validation library do you use?
+- How do you handle type inference?
+-->
+
+(To be filled by the team)
+
+---
+
+## Type Organization
+
+<!-- Where types are defined, shared types vs local types -->
+
+(To be filled by the team)
+
+---
+
+## Validation
+
+<!-- Runtime validation patterns (Zod, Yup, io-ts, etc.) -->
+
+(To be filled by the team)
+
+---
+
+## Common Patterns
+
+<!-- Type utilities, generics, type guards -->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- any, type assertions, etc. -->
+
+(To be filled by the team)

package/dist/templates/markdown/spec/guides/code-reuse-thinking-guide.md.txt

@@ -0,0 +1,223 @@
+# Code Reuse Thinking Guide
+
+> **Purpose**: Stop and think before creating new code - does it already exist?
+
+---
+
+## The Problem
+
+**Duplicated code is the #1 source of inconsistency bugs.**
+
+When you copy-paste or rewrite existing logic:
+- Bug fixes don't propagate
+- Behavior diverges over time
+- Codebase becomes harder to understand
+
+---
+
+## Before Writing New Code
+
+### Step 1: Search First
+
+```bash
+# Search for similar function names
+grep -r "functionName" .
+
+# Search for similar logic
+grep -r "keyword" .
+```
+
+### Step 2: Ask These Questions
+
+| Question | If Yes... |
+|----------|-----------|
+| Does a similar function exist? | Use or extend it |
+| Is this pattern used elsewhere? | Follow the existing pattern |
+| Could this be a shared utility? | Create it in the right place |
+| Am I copying code from another file? | **STOP** - extract to shared |
+
+---
+
+## Common Duplication Patterns
+
+### Pattern 1: Copy-Paste Functions
+
+**Bad**: Copying a validation function to another file
+
+**Good**: Extract to shared utilities, import where needed
+
+### Pattern 2: Similar Components
+
+**Bad**: Creating a new component that's 80% similar to existing
+
+**Good**: Extend existing component with props/variants
+
+### Pattern 3: Repeated Constants
+
+**Bad**: Defining the same constant in multiple files
+
+**Good**: Single source of truth, import everywhere
+
+### Pattern 4: Repeated Payload Field Extraction
+
+**Bad**: Multiple consumers cast the same JSON/event fields locally:
+
+```typescript
+const description = (ev as { description?: string }).description;
+const context = (ev as { context?: ContextEntry[] }).context;
+```
+
+This is duplicated contract logic even when the code is only two lines. Each
+consumer now has its own definition of what a valid payload means.
+
+**Good**: Put the decoder, type guard, or projection next to the data owner:
+
+```typescript
+if (isThreadEvent(ev)) {
+  renderThreadEvent(ev);
+}
+```
+
+**Rule**: If the same untyped payload field is read in 2+ places, create a
+shared type guard / normalizer / projection before adding a third reader.
+
+---
+
+## When to Abstract
+
+**Abstract when**:
+- Same code appears 3+ times
+- Logic is complex enough to have bugs
+- Multiple people might need this
+
+**Don't abstract when**:
+- Only used once
+- Trivial one-liner
+- Abstraction would be more complex than duplication
+
+---
+
+## After Batch Modifications
+
+When you've made similar changes to multiple files:
+
+1. **Review**: Did you catch all instances?
+2. **Search**: Run grep to find any missed
+3. **Consider**: Should this be abstracted?
+
+### Reducers Should Use Exhaustive Structure
+
+When state is derived from action-like values (`action`, `kind`, `status`,
+`phase`), prefer a reducer with one `switch` over scattered `if/else` updates.
+
+```typescript
+// BAD - action-specific state transitions are hard to audit
+if (action === "opened") { ... }
+else if (action === "comment") { ... }
+else if (action === "status") { ... }
+
+// GOOD - one reducer owns the transition table
+switch (event.action) {
+  case "opened":
+    ...
+    return;
+  case "comment":
+    ...
+    return;
+}
+```
+
+This matters when the event log is the source of truth. A reducer is the
+documented replay model; display code and commands should not duplicate pieces
+of that replay model.
+
+---
+
+## Checklist Before Commit
+
+- [ ] Searched for existing similar code
+- [ ] No copy-pasted logic that should be shared
+- [ ] No repeated untyped payload field extraction outside a shared decoder
+- [ ] Constants defined in one place
+- [ ] Similar patterns follow same structure
+- [ ] Reducer/action transitions live in one reducer or command dispatcher
+
+---
+
+## Gotcha: Python if/elif/else Exhaustive Check
+
+**Problem**: Python's if/elif/else chains have no compile-time exhaustive check. When you add a new value to a `Literal` type (e.g., `Platform`), existing if/elif/else chains silently fall through to `else` with wrong defaults.
+
+**Symptom**: New platform works partially — some methods return Claude defaults instead of platform-specific values. No error is raised.
+
+**Example** (`cli_adapter.py`):
+```python
+# BAD: "gemini" falls through to else, returns "claude"
+@property
+def cli_name(self) -> str:
+    if self.platform == "opencode":
+        return "opencode"
+    else:
+        return "claude"  # gemini silently gets "claude"!
+
+# GOOD: explicit branch for every platform
+@property
+def cli_name(self) -> str:
+    if self.platform == "opencode":
+        return "opencode"
+    elif self.platform == "gemini":
+        return "gemini"
+    else:
+        return "claude"
+```
+
+**Prevention**: When adding a new value to a Python `Literal` type, search for ALL if/elif/else chains that switch on that type and add explicit branches. Don't rely on `else` being correct for new values.
+
+---
+
+## Gotcha: Asymmetric Mechanisms Producing Same Output
+
+**Problem**: When two different mechanisms must produce the same file set (e.g., recursive directory copy for init vs. manual `files.set()` for update), structural changes (renaming, moving, adding subdirectories) only propagate through the automatic mechanism. The manual one silently drifts.
+
+**Symptom**: Init works perfectly, but update creates files at wrong paths or misses files entirely.
+
+**Prevention**:
+- **Best**: Eliminate the asymmetry — have the manual path call the automatic one (e.g., `collectTemplateFiles()` calls `getAllScripts()` instead of maintaining its own list)
+- **If asymmetry is unavoidable**: Add a regression test that compares outputs from both mechanisms
+- When migrating directory structures, search for ALL code paths that reference the old structure
+
+**Real example**: `trellis update` had a manual `files.set()` list for 11 scripts that `getAllScripts()` already tracked. Fix: replaced the manual list with a `for..of getAllScripts()` loop. See `update.ts` refactor in v0.4.0-beta.3.
+
+---
+
+## Template File Registration (Trellis-specific)
+
+When adding new files to `src/templates/trellis/scripts/`:
+
+**Single registration point**: `src/templates/trellis/index.ts`
+
+1. Add `export const xxxScript = readTemplate("scripts/path/file.py");`
+2. Add to `getAllScripts()` Map
+
+That's it. `commands/update.ts` uses `getAllScripts()` directly — no manual sync needed.
+
+**Why this matters**: Without registration in `getAllScripts()`, `trellis update` won't sync the file to user projects. Bug fixes and features won't propagate.
+
+**History**: Before v0.4.0-beta.3, `update.ts` had its own hand-maintained file list that frequently fell out of sync with `getAllScripts()`. This caused 11 Python files to be silently skipped during `trellis update`. The fix was to eliminate the duplicate list and use `getAllScripts()` as the single source of truth.
+
+### Quick Checklist for New Scripts
+
+```bash
+# After adding a new .py file, verify it's in getAllScripts():
+grep -l "newFileName" src/templates/trellis/index.ts  # Should match
+```
+
+### Template Sync Convention
+
+`.trellis/scripts/` (dogfooded) and `packages/cli/src/templates/trellis/scripts/` (template) must stay identical. After editing `.trellis/scripts/`, always sync:
+
+```bash
+rsync -av --delete --exclude='__pycache__' .trellis/scripts/ packages/cli/src/templates/trellis/scripts/
+```
+
+**Gotcha**: Running rsync with wrong source/destination paths can create nested garbage directories (e.g., `.trellis/scripts/packages/cli/...`). Always double-check paths before running.