@mindfoldhq/trellis 0.1.0

package/dist/templates/markdown/structure/guides/index.md.txt

@@ -0,0 +1,79 @@
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

package/dist/templates/markdown/workflow.md.txt

@@ -0,0 +1,335 @@
+# Development Workflow
+
+> Based on [Effective Harnesses for Long-Running Agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents)
+
+---
+
+## Table of Contents
+
+1. [Workflow Overview](#workflow-overview)
+2. [Session Start Process](#session-start-process)
+3. [Development Process](#development-process)
+4. [Session End](#session-end)
+5. [File Descriptions](#file-descriptions)
+6. [Best Practices](#best-practices)
+
+---
+
+## Workflow Overview
+
+### Core Principles
+
+1. **Read Before Write** - Understand context before starting
+2. **Follow Standards** - [!] **MUST read `.trellis/structure/` guidelines before coding**
+3. **Incremental Development** - Complete one feature at a time
+4. **Record Promptly** - Update tracking files immediately after completion
+5. **Document Limits** - [!] **Max 2000 lines per agent-traces document**
+
+### File System
+
+```
+.trellis/
+|-- .developer           # Developer identity (gitignored)
+|-- scripts/
+|   |-- common/              # Shared utilities
+|   |   |-- paths.sh         # Path utilities
+|   |   |-- developer.sh     # Developer management
+|   |   \-- git-context.sh   # Git context implementation
+|   |-- init-developer.sh    # Initialize developer identity
+|   |-- get-developer.sh     # Get current developer name
+|   |-- feature.sh           # Manage features
+|   |-- get-context.sh       # Get session context
+|   \-- add-session.sh       # One-click session recording
+|-- agent-traces/       # AI Agent work progress records
+|   |-- index.md         # Progress index + Session template
+|   \-- {developer}/     # Per-developer directories
+|       |-- index.md     # Personal index (with @@@auto markers)
+|       |-- features/    # Feature directories
+|       |   \-- {day}-{name}/
+|       |       \-- feature.json
+|       \-- progress-N.md  # Progress files (sequential numbering)
+|-- structure/           # [!] MUST READ before coding
+|   |-- frontend/        # Frontend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   \-- *.md                   # Topic-specific docs
+|   |-- backend/         # Backend guidelines (if applicable)
+|   |   |-- index.md               # Start here - guidelines index
+|   |   \-- *.md                   # Topic-specific docs
+|   \-- guides/          # Thinking guides
+|       |-- index.md                      # Guides index
+|       |-- cross-layer-thinking-guide.md # Pre-implementation checklist
+|       \-- *.md                          # Other guides
+\-- workflow.md             # This document
+```
+
+---
+
+## Session Start Process
+
+### Step 1: Get Session Context
+
+Use the unified context script:
+
+```bash
+# Get all context in one command
+./.trellis/scripts/get-context.sh
+
+# Or get JSON format
+./.trellis/scripts/get-context.sh --json
+```
+
+### Step 2: Read Development Guidelines [!] REQUIRED
+
+**[!] CRITICAL: MUST read guidelines before writing any code**
+
+Based on what you'll develop, read the corresponding guidelines:
+
+**Frontend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/structure/frontend/index.md
+```
+
+**Backend Development** (if applicable):
+```bash
+# Read index first, then specific docs based on task
+cat .trellis/structure/backend/index.md
+```
+
+**Cross-Layer Features**:
+```bash
+# For features spanning multiple layers
+cat .trellis/structure/guides/cross-layer-thinking-guide.md
+```
+
+### Step 3: Select Feature to Develop
+
+Use the feature management script:
+
+```bash
+# List active features
+./.trellis/scripts/feature.sh list
+
+# Create new feature (creates directory with feature.json)
+./.trellis/scripts/feature.sh create <feature-name>
+```
+
+---
+
+## Development Process
+
+### Feature Development Flow
+
+```
+1. Create or select feature
+   \-> ./.trellis/scripts/feature.sh create <name> or list
+
+2. Write code according to guidelines
+   \-> Read .trellis/structure/ docs relevant to your task
+   \-> For cross-layer: read .trellis/structure/guides/
+
+3. Self-test
+   \-> Run project's lint/test commands (see structure docs)
+   \-> Manual feature testing
+
+4. Commit code
+   \-> git add <files>
+   \-> git commit -m "type(scope): description"
+       Format: feat/fix/docs/refactor/test/chore
+
+5. Record session (one command)
+   \-> ./.trellis/scripts/add-session.sh --title "Title" --commit "hash"
+```
+
+### Code Quality Checklist
+
+**Must pass before commit**:
+- [OK] Lint checks pass (project-specific command)
+- [OK] Type checks pass (if applicable)
+- [OK] Manual feature testing passes
+
+**Project-specific checks**:
+- See `.trellis/structure/frontend/quality-guidelines.md` for frontend
+- See `.trellis/structure/backend/quality-guidelines.md` for backend
+
+---
+
+## Session End
+
+### One-Click Session Recording
+
+After code is committed, use:
+
+```bash
+./.trellis/scripts/add-session.sh \
+  --title "Session Title" \
+  --commit "abc1234" \
+  --summary "Brief summary"
+```
+
+This automatically:
+1. Detects current progress file
+2. Creates new file if 2000-line limit exceeded
+3. Appends session content
+4. Updates index.md (sessions count, history table)
+
+### Pre-end Checklist
+
+Use `/finish-work` command to run through:
+1. [OK] All code committed, commit message follows convention
+2. [OK] Session recorded via `add-session.sh`
+3. [OK] No lint/test errors
+4. [OK] Working directory clean (or WIP noted)
+5. [OK] Structure docs updated if needed
+
+---
+
+## File Descriptions
+
+### 1. agent-traces/ - Agent Work Progress
+
+**Purpose**: Record each AI Agent session's work content
+
+**Structure** (Multi-developer support):
+```
+agent-traces/
+|-- index.md              # Main index (Active Developers table)
+\-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index (with @@@auto markers)
+    |-- features/         # Feature directories
+    |   \-- {day}-{name}/ # Each feature is a directory
+    |       \-- feature.json
+    \-- progress-N.md     # Progress files (sequential: 1, 2, 3...)
+```
+
+**When to update**:
+- [OK] End of each session
+- [OK] Complete important feature
+- [OK] Fix important bug
+
+### 2. structure/ - Development Guidelines
+
+**Purpose**: Documented standards for consistent development
+
+**Structure** (Multi-doc format):
+```
+structure/
+|-- frontend/           # Frontend docs (if applicable)
+|   |-- index.md        # Start here
+|   \-- *.md            # Topic-specific docs
+|-- backend/            # Backend docs (if applicable)
+|   |-- index.md        # Start here
+|   \-- *.md            # Topic-specific docs
+\-- guides/             # Thinking guides
+    |-- index.md        # Start here
+    \-- *.md            # Guide-specific docs
+```
+
+**When to update**:
+- [OK] New pattern discovered
+- [OK] Bug fixed that reveals missing guidance
+- [OK] New convention established
+
+### 3. Features - Feature Tracking
+
+Each feature is a directory containing `feature.json`:
+
+```
+features/
+|-- 13-my-feature/
+|   \-- feature.json
+\-- archive/
+    \-- 2025-01/
+        \-- 13-old-feature/
+            \-- feature.json
+```
+
+**Commands**:
+```bash
+./.trellis/scripts/feature.sh create <name>   # Create feature directory
+./.trellis/scripts/feature.sh archive <name>  # Archive to archive/{year-month}/
+./.trellis/scripts/feature.sh list            # List active features
+./.trellis/scripts/feature.sh list-archive    # List archived features
+```
+
+---
+
+## Best Practices
+
+### [OK] DO - Should Do
+
+1. **Before session start**:
+   - Run `./.trellis/scripts/get-context.sh` for full context
+   - [!] **MUST read** relevant `.trellis/structure/` docs
+
+2. **During development**:
+   - [!] **Follow** `.trellis/structure/` guidelines
+   - For cross-layer features, use `/check-cross-layer`
+   - Develop only one feature at a time
+   - Run lint and tests frequently
+
+3. **After development complete**:
+   - Use `/finish-work` for completion checklist
+   - After fix bug, use `/break-loop` for deep analysis
+   - Human commits after testing passes
+   - Use `add-session.sh` to record progress
+
+### [X] DON'T - Should Not Do
+
+1. [!] **Don't** skip reading `.trellis/structure/` guidelines
+2. [!] **Don't** let agent-traces single file exceed 2000 lines
+3. **Don't** develop multiple unrelated features simultaneously
+4. **Don't** commit code with lint/test errors
+5. **Don't** forget to update structure docs after learning something
+6. [!] **Don't** execute `git commit` - AI should not commit code
+
+---
+
+## Quick Reference
+
+### Must-read Before Development
+
+| Task Type | Must-read Document |
+|-----------|-------------------|
+| Frontend work | `frontend/index.md` → relevant docs |
+| Backend work | `backend/index.md` → relevant docs |
+| Cross-Layer Feature | `guides/cross-layer-thinking-guide.md` |
+
+### Commit Convention
+
+```bash
+git commit -m "type(scope): description"
+```
+
+**Type**: feat, fix, docs, refactor, test, chore
+**Scope**: Module name (e.g., auth, api, ui)
+
+### Common Commands
+
+```bash
+# Session management
+./.trellis/scripts/get-context.sh    # Get full context
+./.trellis/scripts/add-session.sh    # Record session
+
+# Feature management
+./.trellis/scripts/feature.sh list   # List features
+./.trellis/scripts/feature.sh create # Create feature
+
+# Slash commands
+/finish-work          # Pre-commit checklist
+/break-loop           # Post-debug analysis
+/check-cross-layer    # Cross-layer verification
+```
+
+---
+
+## Summary
+
+Following this workflow ensures:
+- [OK] Continuity across multiple sessions
+- [OK] Consistent code quality
+- [OK] Trackable progress
+- [OK] Knowledge accumulation in structure docs
+- [OK] Transparent team collaboration
+
+**Core Philosophy**: Read before write, follow standards, record promptly, capture learnings