@mindfoldhq/trellis 0.1.0

package/dist/templates/commands/common/onboard-developer.txt

@@ -0,0 +1,355 @@
+You are a senior developer onboarding a new team member to this project's AI-assisted workflow system.
+
+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.
+
+## CRITICAL INSTRUCTION - YOU MUST COMPLETE ALL SECTIONS
+
+This onboarding has THREE equally important parts:
+
+**PART 1: Core Concepts** (Sections: CORE PHILOSOPHY, SYSTEM STRUCTURE, COMMAND DEEP DIVE)
+- Explain WHY this workflow exists
+- Explain WHAT each command does and WHY
+
+**PART 2: Real-World Examples** (Section: REAL-WORLD WORKFLOW EXAMPLES)
+- Walk through ALL 5 examples in detail
+- For EACH step in EACH example, explain:
+  - PRINCIPLE: Why this step exists
+  - WHAT HAPPENS: What the command actually does
+  - IF SKIPPED: What goes wrong without it
+
+**PART 3: Customize Your Development Guidelines** (Section: CUSTOMIZE YOUR DEVELOPMENT GUIDELINES)
+- Check if project guidelines are still empty templates
+- If empty, guide the developer to fill them with project-specific content
+- Explain the customization workflow
+
+DO NOT skip any part. All three parts are essential:
+- Part 1 teaches the concepts
+- Part 2 shows how concepts work in practice
+- Part 3 ensures the project has proper guidelines for AI to follow
+
+After completing ALL THREE parts, ask the developer about their first task.
+
+---
+
+## CORE PHILOSOPHY: Why This Workflow Exists
+
+AI-assisted development has three fundamental challenges:
+
+### Challenge 1: AI Has No Memory
+
+Every AI session starts with a blank slate. Unlike human engineers who accumulate project knowledge over weeks/months, AI forgets everything when a session ends.
+
+**The Problem**: Without memory, AI asks the same questions repeatedly, makes the same mistakes, and can't build on previous work.
+
+**The Solution**: The `.trellis/agent-traces/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/start` command reads this history at session start, giving AI "artificial memory."
+
+### Challenge 2: AI Has Generic Knowledge, Not Project-Specific Knowledge
+
+AI models are trained on millions of codebases - they know general patterns for React, TypeScript, databases, etc. But they don't know YOUR project's conventions.
+
+**The Problem**: AI writes code that "works" but doesn't match your project's style. It uses patterns that conflict with existing code. It makes decisions that violate unwritten team rules.
+
+**The Solution**: The `.trellis/structure/` directory contains project-specific guidelines. The `/before-*-dev` commands inject this specialized knowledge into AI context before coding starts.
+
+### Challenge 3: AI Context Window Is Limited
+
+Even after injecting guidelines, AI has limited context window. As conversation grows, earlier context (including guidelines) gets pushed out or becomes less influential.
+
+**The Problem**: AI starts following guidelines, but as the session progresses and context fills up, it "forgets" the rules and reverts to generic patterns.
+
+**The Solution**: The `/check-*` commands re-verify code against guidelines AFTER writing, catching drift that occurred during development. The `/finish-work` command does a final holistic review.
+
+---
+
+## SYSTEM STRUCTURE
+
+```
+.trellis/
+|-- .developer              # Your identity (gitignored)
+|-- workflow.md                 # Complete workflow documentation
+|-- agent-traces/         # "AI Memory" - session history
+|   |-- index.md            # All developers' progress
+|   \-- {developer}/        # Per-developer directory
+|       |-- index.md        # Personal progress index
+|       |-- features/       # Active feature tracking
+|       \-- progress-N.md   # Session records (max 2000 lines)
+|-- structure/              # "AI Training Data" - project knowledge
+|   |-- frontend/           # Frontend conventions
+|   |-- backend/            # Backend conventions
+|   \-- guides/             # Thinking patterns
+\-- scripts/                # Automation tools
+```
+
+### Understanding structure/ subdirectories
+
+**frontend/** - Single-layer frontend knowledge:
+- Component patterns (how to write components in THIS project)
+- State management rules (Redux? Zustand? Context?)
+- Styling conventions (CSS modules? Tailwind? Styled-components?)
+- Hook patterns (custom hooks, data fetching)
+
+**backend/** - Single-layer backend knowledge:
+- API design patterns (REST? GraphQL? tRPC?)
+- Database conventions (query patterns, migrations)
+- Error handling standards
+- Logging and monitoring rules
+
+**guides/** - Cross-layer thinking guides:
+- Code reuse thinking guide
+- Cross-layer thinking guide
+- Pre-implementation checklists
+
+---
+
+## COMMAND DEEP DIVE
+
+### /start - Restore AI Memory
+
+**WHY IT EXISTS**:
+When a human engineer joins a project, they spend days/weeks learning: What is this project? What's been built? What's in progress? What's the current state?
+
+AI needs the same onboarding - but compressed into seconds at session start.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reads developer identity (who am I in this project?)
+2. Checks git status (what branch? uncommitted changes?)
+3. Reads recent session history from `agent-traces/` (what happened before?)
+4. Identifies active features (what's in progress?)
+5. Understands current project state before making any changes
+
+**WHY THIS MATTERS**:
+- Without /start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
+- With /start: AI knows project context, can continue where previous session left off, avoids conflicts.
+
+---
+
+### /before-frontend-dev and /before-backend-dev - Inject Specialized Knowledge
+
+**WHY IT EXISTS**:
+AI models have "pre-trained knowledge" - general patterns from millions of codebases. But YOUR project has specific conventions that differ from generic patterns.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reads `.trellis/structure/frontend/` or `.trellis/structure/backend/`
+2. Loads project-specific patterns into AI's working context:
+   - Component naming conventions
+   - State management patterns
+   - Database query patterns
+   - Error handling standards
+
+**WHY THIS MATTERS**:
+- Without before-*-dev: AI writes generic code that doesn't match project style.
+- With before-*-dev: AI writes code that looks like the rest of the codebase.
+
+---
+
+### /check-frontend and /check-backend - Combat Context Drift
+
+**WHY IT EXISTS**:
+AI context window has limited capacity. As conversation progresses, guidelines injected at session start become less influential. This causes "context drift."
+
+**WHAT IT ACTUALLY DOES**:
+1. Re-reads the guidelines that were injected earlier
+2. Compares written code against those guidelines
+3. Runs type checker and linter
+4. Identifies violations and suggests fixes
+
+**WHY THIS MATTERS**:
+- Without check-*: Context drift goes unnoticed, code quality degrades.
+- With check-*: Drift is caught and corrected before commit.
+
+---
+
+### /check-cross-layer - Multi-Dimension Verification
+
+**WHY IT EXISTS**:
+Most bugs don't come from lack of technical skill - they come from "didn't think of it":
+- Changed a constant in one place, missed 5 other places
+- Modified database schema, forgot to update the API layer
+- Created a utility function, but similar one already exists
+
+**WHAT IT ACTUALLY DOES**:
+1. Identifies which dimensions your change involves
+2. For each dimension, runs targeted checks:
+   - Cross-layer data flow
+   - Code reuse analysis
+   - Import path validation
+   - Consistency checks
+
+---
+
+### /finish-work - Holistic Pre-Commit Review
+
+**WHY IT EXISTS**:
+The `/check-*` commands focus on code quality within a single layer. But real changes often have cross-cutting concerns.
+
+**WHAT IT ACTUALLY DOES**:
+1. Reviews all changes holistically
+2. Checks cross-layer consistency
+3. Identifies broader impacts
+4. Checks if new patterns should be documented
+
+---
+
+### /record-agent-flow - Persist Memory for Future
+
+**WHY IT EXISTS**:
+All the context AI built during this session will be lost when session ends. The next session's `/start` needs this information.
+
+**WHAT IT ACTUALLY DOES**:
+1. Records session summary to `agent-traces/{developer}/progress-N.md`
+2. Captures what was done, learned, and what's remaining
+3. Updates index files for quick lookup
+
+---
+
+## REAL-WORLD WORKFLOW EXAMPLES
+
+### Example 1: Bug Fix Session
+
+**[1/8] /start** - AI needs project context before touching code
+**[2/8] ./.trellis/scripts/feature.sh create fix-bug** - Track work for future reference
+**[3/8] /before-frontend-dev** - Inject project-specific frontend knowledge
+**[4/8] Investigate and fix the bug** - Actual development work
+**[5/8] /check-frontend** - Re-verify code against guidelines
+**[6/8] /finish-work** - Holistic cross-layer review
+**[7/8] Human tests and commits** - Human validates before code enters repo
+**[8/8] /record-agent-flow** - Persist memory for future sessions
+
+### Example 2: Planning Session (No Code)
+
+**[1/4] /start** - Context needed even for non-coding work
+**[2/4] ./.trellis/scripts/feature.sh create planning-task** - Planning is valuable work
+**[3/4] Review docs, create subtask list** - Actual planning work
+**[4/4] /record-agent-flow (with --summary)** - Planning decisions must be recorded
+
+### Example 3: Code Review Fixes
+
+**[1/6] /start** - Resume context from previous session
+**[2/6] /before-backend-dev** - Re-inject guidelines before fixes
+**[3/6] Fix each CR issue** - Address feedback with guidelines in context
+**[4/6] /check-backend** - Verify fixes didn't introduce new issues
+**[5/6] /finish-work** - Document lessons from CR
+**[6/6] Human commits, then /record-agent-flow** - Preserve CR lessons
+
+### Example 4: Large Refactoring
+
+**[1/5] /start** - Clear baseline before major changes
+**[2/5] Plan phases** - Break into verifiable chunks
+**[3/5] Execute phase by phase with /check-* after each** - Incremental verification
+**[4/5] /finish-work** - Check if new patterns should be documented
+**[5/5] Record with multiple commit hashes** - Link all commits to one feature
+
+### Example 5: Debug Session
+
+**[1/6] /start** - See if this bug was investigated before
+**[2/6] /before-backend-dev** - Guidelines might document known gotchas
+**[3/6] Investigation** - Actual debugging work
+**[4/6] /check-backend** - Verify debug changes don't break other things
+**[5/6] /finish-work** - Debug findings might need documentation
+**[6/6] Human commits, then /record-agent-flow** - Debug knowledge is valuable
+
+---
+
+## KEY RULES TO EMPHASIZE
+
+1. **AI NEVER commits** - Human tests and approves. AI prepares, human validates.
+2. **Guidelines before code** - /before-*-dev commands inject project knowledge.
+3. **Check after code** - /check-* commands catch context drift.
+4. **Record everything** - /record-agent-flow persists memory.
+
+---
+
+# PART 3: Customize Your Development Guidelines
+
+After explaining Part 1 and Part 2, check if the project's development guidelines need customization.
+
+## Step 1: Check Current Guidelines Status
+
+Check if `.trellis/structure/` contains empty templates or customized guidelines:
+
+```bash
+# Check if files are still empty templates (look for placeholder text)
+grep -l "To be filled by the team" .trellis/structure/backend/*.md 2>/dev/null | wc -l
+grep -l "To be filled by the team" .trellis/structure/frontend/*.md 2>/dev/null | wc -l
+```
+
+## Step 2: Determine Situation
+
+**Situation A: First-time setup (empty templates)**
+
+If guidelines are empty templates (contain "To be filled by the team"), this is the first time using Trellis in this project.
+
+Explain to the developer:
+
+"I see that the development guidelines in `.trellis/structure/` are still empty templates. This is normal for a new Trellis setup!
+
+The templates contain placeholder text that needs to be replaced with YOUR project's actual conventions. Without this, `/before-*-dev` commands won't provide useful guidance.
+
+**Your first task should be to fill in these guidelines:**
+
+1. Look at your existing codebase
+2. Identify the patterns and conventions already in use
+3. Document them in the guideline files
+
+For example, for `.trellis/structure/backend/database-guidelines.md`:
+- What ORM/query library does your project use?
+- How are migrations managed?
+- What naming conventions for tables/columns?
+
+Would you like me to help you analyze your codebase and fill in these guidelines?"
+
+**Situation B: Guidelines already customized**
+
+If guidelines have real content (no "To be filled" placeholders), this is an existing setup.
+
+Explain to the developer:
+
+"Great! Your team has already customized the development guidelines. You can start using `/before-*-dev` commands right away.
+
+I recommend reading through `.trellis/structure/` to familiarize yourself with the team's coding standards."
+
+## Step 3: Help Fill Guidelines (If Empty)
+
+If the developer wants help filling guidelines, create a feature to track this:
+
+```bash
+./.trellis/scripts/feature.sh create fill-structure-guidelines
+```
+
+Then systematically analyze the codebase and fill each guideline file:
+
+1. **Analyze the codebase** - Look at existing code patterns
+2. **Document conventions** - Write what you observe, not ideals
+3. **Include examples** - Reference actual files in the project
+4. **List forbidden patterns** - Document anti-patterns the team avoids
+
+Work through one file at a time:
+- `backend/directory-structure.md`
+- `backend/database-guidelines.md`
+- `backend/error-handling.md`
+- `backend/quality-guidelines.md`
+- `backend/logging-guidelines.md`
+- `frontend/directory-structure.md`
+- `frontend/component-guidelines.md`
+- `frontend/hook-guidelines.md`
+- `frontend/state-management.md`
+- `frontend/quality-guidelines.md`
+- `frontend/type-safety.md`
+
+---
+
+## Completing the Onboard Session
+
+After covering all three parts, summarize:
+
+"You're now onboarded to the Trellis workflow system! Here's what we covered:
+- Part 1: Core concepts (why this workflow exists)
+- Part 2: Real-world examples (how to apply the workflow)
+- Part 3: Guidelines status (empty templates need filling / already customized)
+
+**Next steps** (tell user):
+1. Run `/record-agent-flow` to record this onboard session
+2. [If guidelines empty] Start filling in `.trellis/structure/` guidelines
+3. [If guidelines ready] Start your first development task
+
+What would you like to do first?"

package/dist/templates/commands/common/record-agent-flow.txt

@@ -0,0 +1,62 @@
+[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
+
+**AI must NOT execute git commit** - only read history (`git log`, `git status`, `git diff`).
+
+---
+
+## Record Work Progress (Simplified - Only 2 Steps)
+
+### Step 1: Get Context
+
+```bash
+./.trellis/scripts/get-context.sh
+```
+
+### Step 2: One-Click Add Session
+
+```bash
+# Method 1: Simple parameters
+./.trellis/scripts/add-session.sh \
+  --title "Session Title" \
+  --commit "hash1,hash2" \
+  --summary "Brief summary of what was done"
+
+# Method 2: Pass detailed content via stdin
+cat << 'EOF' | ./.trellis/scripts/add-session.sh --title "Title" --commit "hash"
+| Feature | Description |
+|---------|-------------|
+| New API | Added user authentication endpoint |
+| Frontend | Updated login form |
+
+**Updated Files**:
+- `packages/api/modules/auth/router.ts`
+- `apps/web/modules/auth/components/login-form.tsx`
+EOF
+```
+
+**Auto-completes**:
+- [OK] Appends session to progress-N.md
+- [OK] Auto-detects line count, creates new file if >2000 lines
+- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
+
+---
+
+## Archive Completed Feature (if any)
+
+If a feature was completed this session:
+
+```bash
+./.trellis/scripts/feature.sh archive <feature-name>
+```
+
+---
+
+## Script Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `get-context.sh` | Get all context info |
+| `add-session.sh --title "..." --commit "..."` | **One-click add session (recommended)** |
+| `feature.sh create <name>` | Create new feature directory |
+| `feature.sh archive <name>` | Archive completed feature |
+| `feature.sh list` | List active features |

package/dist/templates/commands/cursor/start.md.txt

@@ -0,0 +1,94 @@
+# Initialize AI Agent Session
+
+Read project context and prepare for development work.
+
+---
+
+## Execution Steps
+
+### Step 1: Get Session Context
+
+```bash
+./.trellis/scripts/get-context.sh
+```
+
+This returns:
+- Developer identity
+- Git status (branch, uncommitted changes)
+- Recent commits
+- Active features
+- Progress file status
+
+### Step 2: Read Relevant Guidelines
+
+Based on the upcoming task, read appropriate structure docs:
+
+**For Frontend Work**:
+```bash
+cat .trellis/structure/frontend/index.md
+```
+Then read specific docs based on task type.
+
+**For Backend Work**:
+```bash
+cat .trellis/structure/backend/index.md
+```
+Then read specific docs based on task type.
+
+**For Cross-Layer Features**:
+```bash
+cat .trellis/structure/guides/index.md
+cat .trellis/structure/guides/cross-layer-thinking-guide.md
+```
+
+### Step 3: Check Active Features
+
+```bash
+./.trellis/scripts/feature.sh list
+```
+
+If continuing previous work, review the feature file.
+
+### Step 4: Report Ready Status
+
+Output a summary:
+
+```markdown
+## Session Initialized
+
+| Item | Status |
+|------|--------|
+| Developer | {name} |
+| Branch | {branch} |
+| Uncommitted | {count} file(s) |
+| Progress | {file} ({lines}/2000 lines) |
+| Active Features | {count} |
+
+### Available Commands
+- `/before-frontend-dev` - Read frontend guidelines
+- `/before-backend-dev` - Read backend guidelines
+- `/check-cross-layer` - Cross-layer verification
+- `/finish-work` - Pre-commit checklist
+- `/record-agent-flow` - Record session progress
+
+Ready for your task. What would you like to work on?
+```
+
+---
+
+## Quick Reference
+
+| Scenario | Next Step |
+|----------|-----------|
+| New feature | Run `./.trellis/scripts/feature.sh create <name>` |
+| Continue feature | Read feature file, continue work |
+| Bug fix | Investigate, fix, then remind user to run `/break-loop` |
+| First time | Remind user to run `/onboard-developer` for full setup |
+
+---
+
+## Notes
+
+- Always read structure guidelines before coding
+- One feature at a time
+- At session end, remind user to run `/record-agent-flow` to record progress

package/dist/templates/commands/index.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Command templates for Trellis workflow
+ *
+ * All templates are in common/ and work with all supported AI tools.
+ * The claude/ directory is reserved for future Claude-specific commands.
+ */
+import type { AITool, TemplateDir } from "../../types/ai-tools.js";
+export declare const claudeStartTemplate: string;
+export declare const cursorStartTemplate: string;
+export declare const recordAgentFlowTemplate: string;
+export declare const onboardDeveloperTemplate: string;
+export declare const checkFrontendTemplate: string;
+export declare const checkBackendTemplate: string;
+export declare const checkCrossLayerTemplate: string;
+export declare const beforeFrontendDevTemplate: string;
+export declare const beforeBackendDevTemplate: string;
+export declare const finishWorkTemplate: string;
+export declare const breakLoopTemplate: string;
+export declare const createCommandTemplate: string;
+export declare const integrateSkillTemplate: string;
+/**
+ * Command template definition
+ */
+export interface CommandTemplate {
+    /** Command name (used for filename) */
+    name: string;
+    /** Template content */
+    content: string;
+    /** Human-readable description */
+    description: string;
+    /** Which directory this template belongs to */
+    category: TemplateDir;
+}
+/**
+ * Get command templates available for a specific AI tool
+ */
+export declare function getTemplatesForTool(tool: AITool): CommandTemplate[];
+/**
+ * Get all command templates
+ */
+export declare function getAllTemplates(): CommandTemplate[];
+/**
+ * Get a specific template by name
+ */
+export declare function getTemplateByName(name: string): CommandTemplate | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/commands/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/commands/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAmBnE,eAAO,MAAM,mBAAmB,EAAE,MAGjC,CAAC;AAGF,eAAO,MAAM,mBAAmB,EAAE,MAGjC,CAAC;AAOF,eAAO,MAAM,uBAAuB,EAAE,MAGrC,CAAC;AACF,eAAO,MAAM,wBAAwB,EAAE,MAGtC,CAAC;AAGF,eAAO,MAAM,qBAAqB,EAAE,MAGnC,CAAC;AACF,eAAO,MAAM,oBAAoB,EAAE,MAGlC,CAAC;AACF,eAAO,MAAM,uBAAuB,EAAE,MAGrC,CAAC;AAGF,eAAO,MAAM,yBAAyB,EAAE,MAGvC,CAAC;AACF,eAAO,MAAM,wBAAwB,EAAE,MAGtC,CAAC;AAGF,eAAO,MAAM,kBAAkB,EAAE,MAGhC,CAAC;AACF,eAAO,MAAM,iBAAiB,EAAE,MAG/B,CAAC;AAGF,eAAO,MAAM,qBAAqB,EAAE,MAGnC,CAAC;AACF,eAAO,MAAM,sBAAsB,EAAE,MAGpC,CAAC;AAMF;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,WAAW,CAAC;CACvB;AA0FD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,EAAE,CAGnE;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,eAAe,EAAE,CAEnD;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,SAAS,CAE3E"}