@mindfoldhq/trellis 0.4.0-beta.9 → 0.4.0-rc.1

package/dist/templates/droid/commands/trellis/break-loop.md

@@ -0,0 +1,111 @@
+---
+description: Deep bug analysis to break the fix-forget-repeat cycle
+---
+
+# Break the Loop - Deep Bug Analysis
+
+When debug is complete, use this command for deep analysis to break the "fix bug -> forget -> repeat" cycle.
+
+---
+
+## Analysis Framework
+
+Analyze the bug you just fixed from these 5 dimensions:
+
+### 1. Root Cause Category
+
+Which category does this bug belong to?
+
+| Category | Characteristics | Example |
+|----------|-----------------|---------|
+| **A. Missing Spec** | No documentation on how to do it | New feature without checklist |
+| **B. Cross-Layer Contract** | Interface between layers unclear | API returns different format than expected |
+| **C. Change Propagation Failure** | Changed one place, missed others | Changed function signature, missed call sites |
+| **D. Test Coverage Gap** | Unit test passes, integration fails | Works alone, breaks when combined |
+| **E. Implicit Assumption** | Code relies on undocumented assumption | Timestamp seconds vs milliseconds |
+
+### 2. Why Fixes Failed (if applicable)
+
+If you tried multiple fixes before succeeding, analyze each failure:
+
+- **Surface Fix**: Fixed symptom, not root cause
+- **Incomplete Scope**: Found root cause, didn't cover all cases
+- **Tool Limitation**: grep missed it, type check wasn't strict
+- **Mental Model**: Kept looking in same layer, didn't think cross-layer
+
+### 3. Prevention Mechanisms
+
+What mechanisms would prevent this from happening again?
+
+| Type | Description | Example |
+|------|-------------|---------|
+| **Documentation** | Write it down so people know | Update thinking guide |
+| **Architecture** | Make the error impossible structurally | Type-safe wrappers |
+| **Compile-time** | TypeScript strict, no any | Signature change causes compile error |
+| **Runtime** | Monitoring, alerts, scans | Detect orphan entities |
+| **Test Coverage** | E2E tests, integration tests | Verify full flow |
+| **Code Review** | Checklist, PR template | "Did you check X?" |
+
+### 4. Systematic Expansion
+
+What broader problems does this bug reveal?
+
+- **Similar Issues**: Where else might this problem exist?
+- **Design Flaw**: Is there a fundamental architecture issue?
+- **Process Flaw**: Is there a development process improvement?
+- **Knowledge Gap**: Is the team missing some understanding?
+
+### 5. Knowledge Capture
+
+Solidify insights into the system:
+
+- [ ] Update `.trellis/spec/guides/` thinking guides
+- [ ] Update `.trellis/spec/backend/` or `frontend/` docs
+- [ ] Create issue record (if applicable)
+- [ ] Create feature ticket for root fix
+- [ ] Update check commands if needed
+
+---
+
+## Output Format
+
+Please output analysis in this format:
+
+```markdown
+## Bug Analysis: [Short Description]
+
+### 1. Root Cause Category
+- **Category**: [A/B/C/D/E] - [Category Name]
+- **Specific Cause**: [Detailed description]
+
+### 2. Why Fixes Failed (if applicable)
+1. [First attempt]: [Why it failed]
+2. [Second attempt]: [Why it failed]
+...
+
+### 3. Prevention Mechanisms
+| Priority | Mechanism | Specific Action | Status |
+|----------|-----------|-----------------|--------|
+| P0 | ... | ... | TODO/DONE |
+
+### 4. Systematic Expansion
+- **Similar Issues**: [List places with similar problems]
+- **Design Improvement**: [Architecture-level suggestions]
+- **Process Improvement**: [Development process suggestions]
+
+### 5. Knowledge Capture
+- [ ] [Documents to update / tickets to create]
+```
+
+---
+
+## Core Philosophy
+
+> **The value of debugging is not in fixing the bug, but in making this class of bugs never happen again.**
+
+Three levels of insight:
+1. **Tactical**: How to fix THIS bug
+2. **Strategic**: How to prevent THIS CLASS of bugs
+3. **Philosophical**: How to expand thinking patterns
+
+30 minutes of analysis saves 30 hours of future debugging.

package/dist/templates/droid/commands/trellis/check-cross-layer.md

@@ -0,0 +1,157 @@
+---
+description: Check whether changes considered all layers and dimensions
+---
+
+# Cross-Layer Check
+
+Check if your changes considered all dimensions. Most bugs come from "didn't think of it", not lack of technical skill.
+
+> **Note**: This is a **post-implementation** safety net. Ideally, read the [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) **before** writing code.
+
+---
+
+## Related Documents
+
+| Document | Purpose | Timing |
+|----------|---------|--------|
+| [Pre-Implementation Checklist](.trellis/spec/guides/pre-implementation-checklist.md) | Questions before coding | **Before** writing code |
+| [Code Reuse Thinking Guide](.trellis/spec/guides/code-reuse-thinking-guide.md) | Pattern recognition | During implementation |
+| **`/trellis-check-cross-layer`** (this) | Verification check | **After** implementation |
+
+---
+
+## Execution Steps
+
+### 1. Identify Change Scope
+
+```bash
+git status
+git diff --name-only
+```
+
+### 2. Select Applicable Check Dimensions
+
+Based on your change type, execute relevant checks below:
+
+---
+
+## Dimension A: Cross-Layer Data Flow (Required when 3+ layers)
+
+**Trigger**: Changes involve 3 or more layers
+
+| Layer | Common Locations |
+|-------|------------------|
+| API/Routes | `routes/`, `api/`, `handlers/`, `controllers/` |
+| Service/Business Logic | `services/`, `lib/`, `core/`, `domain/` |
+| Database/Storage | `db/`, `models/`, `repositories/`, `schema/` |
+| UI/Presentation | `components/`, `views/`, `templates/`, `pages/` |
+| Utility | `utils/`, `helpers/`, `common/` |
+
+**Checklist**:
+- [ ] Read flow: Database -> Service -> API -> UI
+- [ ] Write flow: UI -> API -> Service -> Database
+- [ ] Types/schemas correctly passed between layers?
+- [ ] Errors properly propagated to caller?
+- [ ] Loading/pending states handled at each layer?
+
+**Detailed Guide**: `.trellis/spec/guides/cross-layer-thinking-guide.md`
+
+---
+
+## Dimension B: Code Reuse (Required when modifying constants/config)
+
+**Trigger**: 
+- Modifying UI constants (label, icon, color)
+- Modifying any hardcoded value
+- Seeing similar code in multiple places
+- Creating a new utility/helper function
+- Just finished batch modifications across files
+
+**Checklist**:
+- [ ] Search first: How many places define this value?
+  ```bash
+  # Search in source files (adjust extensions for your project)
+  grep -r "value-to-change" src/
+  ```
+- [ ] If 2+ places define same value -> Should extract to shared constant
+- [ ] After modification, all usage sites updated?
+- [ ] If creating utility: Does similar utility already exist?
+
+**Detailed Guide**: `.trellis/spec/guides/code-reuse-thinking-guide.md`
+
+---
+
+## Dimension B2: New Utility Functions
+
+**Trigger**: About to create a new utility/helper function
+
+**Checklist**:
+- [ ] Search for existing similar utilities first
+  ```bash
+  grep -r "functionNamePattern" src/
+  ```
+- [ ] If similar exists, can you extend it instead?
+- [ ] If creating new, is it in the right location (shared vs domain-specific)?
+
+---
+
+## Dimension B3: After Batch Modifications
+
+**Trigger**: Just modified similar patterns in multiple files
+
+**Checklist**:
+- [ ] Did you check ALL files with similar patterns?
+  ```bash
+  grep -r "patternYouChanged" src/
+  ```
+- [ ] Any files missed that should also be updated?
+- [ ] Should this pattern be abstracted to prevent future duplication?
+
+---
+
+## Dimension C: Import/Dependency Paths (Required when creating new files)
+
+**Trigger**: Creating new source files
+
+**Checklist**:
+- [ ] Using correct import paths (relative vs absolute)?
+- [ ] No circular dependencies?
+- [ ] Consistent with project's module organization?
+
+---
+
+## Dimension D: Same-Layer Consistency
+
+**Trigger**: 
+- Modifying display logic or formatting
+- Same domain concept used in multiple places
+
+**Checklist**:
+- [ ] Search for other places using same concept
+  ```bash
+  grep -r "ConceptName" src/
+  ```
+- [ ] Are these usages consistent?
+- [ ] Should they share configuration/constants?
+
+---
+
+## Common Issues Quick Reference
+
+| Issue | Root Cause | Prevention |
+|-------|------------|------------|
+| Changed one place, missed others | Didn't search impact scope | `grep` before changing |
+| Data lost at some layer | Didn't check data flow | Trace data source to destination |
+| Type/schema mismatch | Cross-layer types inconsistent | Use shared type definitions |
+| UI/output inconsistent | Same concept in multiple places | Extract shared constants |
+| Similar utility exists | Didn't search first | Search before creating |
+| Batch fix incomplete | Didn't verify all occurrences | grep after fixing |
+
+---
+
+## Output
+
+Report:
+1. Which dimensions your changes involve
+2. Check results for each dimension
+3. Issues found and fix suggestions

package/dist/templates/droid/commands/trellis/check.md

@@ -0,0 +1,29 @@
+---
+description: Verify the code you just wrote follows the development guidelines
+---
+
+Check if the code you just wrote follows the development guidelines.
+
+Execute these steps:
+
+1. **Identify changed files**:
+   ```bash
+   git diff --name-only HEAD
+   ```
+
+2. **Determine which spec modules apply** based on the changed file paths:
+   ```bash
+   python3 ./.trellis/scripts/get_context.py --mode packages
+   ```
+
+3. **Read the spec index** for each relevant module:
+   ```bash
+   cat .trellis/spec/<package>/<layer>/index.md
+   ```
+   Follow the **"Quality Check"** section in the index.
+
+4. **Read the specific guideline files** referenced in the Quality Check section (e.g., `quality-guidelines.md`, `conventions.md`). The index is NOT the goal — it points you to the actual guideline files. Read those files and review your code against them.
+
+5. **Run lint and typecheck** for the affected package.
+
+6. **Report any violations** and fix them if found.

package/dist/templates/droid/commands/trellis/create-command.md

@@ -0,0 +1,158 @@
+---
+description: Create a new Trellis slash command across supported platforms
+---
+
+# Create New Slash Command
+
+Create a new slash command in both `.cursor/commands/` (with `trellis-` prefix) and `.claude/commands/trellis/` directories based on user requirements.
+
+## Usage
+
+```
+/trellis-create-command <command-name> <description>
+```
+
+**Example**:
+```
+/trellis-create-command review-pr Check PR code changes against project guidelines
+```
+
+## Execution Steps
+
+### 1. Parse Input
+
+Extract from user input:
+- **Command name**: Use kebab-case (e.g., `review-pr`)
+- **Description**: What the command should accomplish
+
+### 2. Analyze Requirements
+
+Determine command type based on description:
+- **Initialization**: Read docs, establish context
+- **Pre-development**: Read guidelines, check dependencies
+- **Code check**: Validate code quality and guideline compliance
+- **Recording**: Record progress, questions, structure changes
+- **Generation**: Generate docs, code templates
+
+### 3. Generate Command Content
+
+Based on command type, generate appropriate content:
+
+**Simple command** (1-3 lines):
+```markdown
+Concise instruction describing what to do
+```
+
+**Complex command** (with steps):
+```markdown
+# Command Title
+
+Command description
+
+## Steps
+
+### 1. First Step
+Specific action
+
+### 2. Second Step
+Specific action
+
+## Output Format (if needed)
+
+Template
+```
+
+### 4. Create Files
+
+Create in both directories:
+- `.cursor/commands/trellis-<command-name>.md`
+- `.claude/commands/trellis/<command-name>.md`
+
+### 5. Confirm Creation
+
+Output result:
+```
+[OK] Created Slash Command: /<command-name>
+
+File paths:
+- .cursor/commands/trellis-<command-name>.md
+- .claude/commands/trellis/<command-name>.md
+
+Usage:
+/trellis-<command-name>
+
+Description:
+<description>
+```
+
+## Command Content Guidelines
+
+### [OK] Good command content
+
+1. **Clear and concise**: Immediately understandable
+2. **Executable**: AI can follow steps directly
+3. **Well-scoped**: Clear boundaries of what to do and not do
+4. **Has output**: Specifies expected output format (if needed)
+
+### [X] Avoid
+
+1. **Too vague**: e.g., "optimize code"
+2. **Too complex**: Single command should not exceed 100 lines
+3. **Duplicate functionality**: Check if similar command exists first
+
+## Naming Conventions
+
+| Command Type | Prefix | Example |
+|--------------|--------|---------|
+| Session Start | `start` | `start` |
+| Pre-development | `before-` | `before-dev` |
+| Check | `check-` | `check` |
+| Record | `record-` | `record-session` |
+| Generate | `generate-` | `generate-api-doc` |
+| Update | `update-` | `update-changelog` |
+| Other | Verb-first | `review-code`, `sync-data` |
+
+## Example
+
+### Input
+```
+/trellis-create-command review-pr Check PR code changes against project guidelines
+```
+
+### Generated Command Content
+```markdown
+# PR Code Review
+
+Check current PR code changes against project guidelines.
+
+## Steps
+
+### 1. Get Changed Files
+```bash
+git diff main...HEAD --name-only
+```
+
+### 2. Categorized Review
+
+**Frontend files** (`apps/web/`):
+- Reference `.trellis/spec/frontend/index.md`
+
+**Backend files** (`packages/api/`):
+- Reference `.trellis/spec/backend/index.md`
+
+### 3. Output Review Report
+
+Format:
+
+## PR Review Report
+
+### Changed Files
+- [file list]
+
+### Check Results
+- [OK] Passed items
+- [X] Issues found
+
+### Suggestions
+- [improvement suggestions]
+```

package/dist/templates/droid/commands/trellis/finish-work.md

@@ -0,0 +1,147 @@
+---
+description: Pre-commit checklist to verify work completeness before submitting
+---
+
+# Finish Work - Pre-Commit Checklist
+
+Before submitting or committing, use this checklist to ensure work completeness.
+
+**Timing**: After code is written and tested, before commit
+
+---
+
+## Checklist
+
+### 1. Code Quality
+
+```bash
+# Must pass
+pnpm lint
+pnpm type-check
+pnpm test
+```
+
+- [ ] `pnpm lint` passes with 0 errors?
+- [ ] `pnpm type-check` passes with no type errors?
+- [ ] Tests pass?
+- [ ] No `console.log` statements (use logger)?
+- [ ] No non-null assertions (the `x!` operator)?
+- [ ] No `any` types?
+
+### 2. Code-Spec Sync
+
+**Code-Spec Docs**:
+- [ ] Does `.trellis/spec/backend/` need updates?
+  - New patterns, new modules, new conventions
+- [ ] Does `.trellis/spec/frontend/` need updates?
+  - New components, new hooks, new patterns
+- [ ] Does `.trellis/spec/guides/` need updates?
+  - New cross-layer flows, lessons from bugs
+
+**Key Question**: 
+> "If I fixed a bug or discovered something non-obvious, should I document it so future me (or others) won't hit the same issue?"
+
+If YES -> Update the relevant code-spec doc.
+
+### 2.5. Code-Spec Hard Block (Infra/Cross-Layer)
+
+If this change touches infra or cross-layer contracts, this is a blocking checklist:
+
+- [ ] Spec content is executable (real signatures/contracts), not principle-only text
+- [ ] Includes file path + command/API name + payload field names
+- [ ] Includes validation and error matrix
+- [ ] Includes Good/Base/Bad cases
+- [ ] Includes required tests and assertion points
+
+**Block Rule**:
+If infra/cross-layer changed but the related spec is still abstract, do NOT finish. Run `/trellis-update-spec` manually first.
+
+### 3. API Changes
+
+If you modified API endpoints:
+
+- [ ] Input schema updated?
+- [ ] Output schema updated?
+- [ ] API documentation updated?
+- [ ] Client code updated to match?
+
+### 4. Database Changes
+
+If you modified database schema:
+
+- [ ] Migration file created?
+- [ ] Schema file updated?
+- [ ] Related queries updated?
+- [ ] Seed data updated (if applicable)?
+
+### 5. Cross-Layer Verification
+
+If the change spans multiple layers:
+
+- [ ] Data flows correctly through all layers?
+- [ ] Error handling works at each boundary?
+- [ ] Types are consistent across layers?
+- [ ] Loading states handled?
+
+### 6. Manual Testing
+
+- [ ] Feature works in browser/app?
+- [ ] Edge cases tested?
+- [ ] Error states tested?
+- [ ] Works after page refresh?
+
+---
+
+## Quick Check Flow
+
+```bash
+# 1. Code checks
+pnpm lint && pnpm type-check
+
+# 2. View changes
+git status
+git diff --name-only
+
+# 3. Based on changed files, check relevant items above
+```
+
+---
+
+## Common Oversights
+
+| Oversight | Consequence | Check |
+|-----------|-------------|-------|
+| Code-spec docs not updated | Others don't know the change | Check .trellis/spec/ |
+| Spec text is abstract only | Easy regressions in infra/cross-layer changes | Require signature/contract/matrix/cases/tests |
+| Migration not created | Schema out of sync | Check db/migrations/ |
+| Types not synced | Runtime errors | Check shared types |
+| Tests not updated | False confidence | Run full test suite |
+| Console.log left in | Noisy production logs | Search for console.log |
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Write code -> Test -> /trellis-finish-work -> git commit -> /trellis-record-session
+                          |                              |
+                   Ensure completeness              Record progress
+                   
+Debug Flow:
+  Hit bug -> Fix -> /trellis-break-loop -> Knowledge capture
+                       |
+                  Deep analysis
+```
+
+- `/trellis-finish-work` - Check work completeness (this command)
+- `/trellis-record-session` - Record session and commits
+- `/trellis-break-loop` - Deep analysis after debugging
+
+---
+
+## Core Principle
+
+> **Delivery includes not just code, but also documentation, verification, and knowledge capture.**
+
+Complete work = Code + Docs + Tests + Verification