@mindfoldhq/trellis 0.4.0 → 0.5.0-beta.10

package/dist/templates/droid/commands/trellis/integrate-skill.md

@@ -1,223 +0,0 @@
----
-description: Adapt and integrate a Claude skill into project development guidelines
----
-
-# Integrate Claude Skill into Project Guidelines
-
-Adapt and integrate a Claude global skill into your project's development guidelines (not directly into project code).
-
-## Usage
-
-```
-/trellis-integrate-skill <skill-name>
-```
-
-**Examples**:
-```
-/trellis-integrate-skill frontend-design
-/trellis-integrate-skill mcp-builder
-```
-
-## Core Principle
-
-> [!] **Important**: The goal of skill integration is to update **development guidelines**, not to generate project code directly.
->
-> - Guidelines content -> Write to `.trellis/spec/{target}/doc.md`
-> - Code examples -> Place in `.trellis/spec/{target}/examples/skills/<skill-name>/`
-> - Example files -> Use `.template` suffix (e.g., `component.tsx.template`) to avoid IDE errors
->
-> Where `{target}` is `frontend` or `backend`, determined by skill type.
-
-## Execution Steps
-
-### 1. Read Skill Content
-
-```bash
-openskills read <skill-name>
-```
-
-If the skill doesn't exist, prompt user to check available skills:
-```bash
-# Available skills are listed in AGENTS.md under <available_skills>
-```
-
-### 2. Determine Integration Target
-
-Based on skill type, determine which guidelines to update:
-
-| Skill Category | Integration Target |
-|----------------|-------------------|
-| UI/Frontend (`frontend-design`, `web-artifacts-builder`) | `.trellis/spec/frontend/` |
-| Backend/API (`mcp-builder`) | `.trellis/spec/backend/` |
-| Documentation (`doc-coauthoring`, `docx`, `pdf`) | `.trellis/` or create dedicated guidelines |
-| Testing (`webapp-testing`) | `.trellis/spec/frontend/` (E2E) |
-
-### 3. Analyze Skill Content
-
-Extract from the skill:
-- **Core concepts**: How the skill works and key concepts
-- **Best practices**: Recommended approaches
-- **Code patterns**: Reusable code templates
-- **Caveats**: Common issues and solutions
-
-### 4. Execute Integration
-
-#### 4.1 Update Guidelines Document
-
-Add a new section to the corresponding `doc.md`:
-
-```markdown
-@@@section:skill-<skill-name>
-## # <Skill Name> Integration Guide
-
-### Overview
-[Core functionality and use cases of the skill]
-
-### Project Adaptation
-[How to use this skill in the current project]
-
-### Usage Steps
-1. [Step 1]
-2. [Step 2]
-
-### Caveats
-- [Project-specific constraints]
-- [Differences from default behavior]
-
-### Reference Examples
-See `examples/skills/<skill-name>/`
-
-@@@/section:skill-<skill-name>
-```
-
-#### 4.2 Create Examples Directory (if code examples exist)
-
-```bash
-# Directory structure ({target} = frontend or backend)
-.trellis/spec/{target}/
-|-- doc.md                      # Add skill-related section
-|-- index.md                    # Update index
-+-- examples/
-    +-- skills/
-        +-- <skill-name>/
-            |-- README.md               # Example documentation
-            |-- example-1.ts.template   # Code example (use .template suffix)
-            +-- example-2.tsx.template
-```
-
-**File naming conventions**:
-- Code files: `<name>.<ext>.template` (e.g., `component.tsx.template`)
-- Config files: `<name>.config.template` (e.g., `tailwind.config.template`)
-- Documentation: `README.md` (normal suffix)
-
-#### 4.3 Update Index File
-
-Add to the Quick Navigation table in `index.md`:
-
-```markdown
-| <Skill-related task> | <Section name> | `skill-<skill-name>` |
-```
-
-### 5. Generate Integration Report
-
----
-
-## Skill Integration Report: `<skill-name>`
-
-### # Overview
-- **Skill description**: [Functionality description]
-- **Integration target**: `.trellis/spec/{target}/`
-
-### # Tech Stack Compatibility
-
-| Skill Requirement | Project Status | Compatibility |
-|-------------------|----------------|---------------|
-| [Tech 1] | [Project tech] | [OK]/[!]/[X] |
-
-### # Integration Locations
-
-| Type | Path |
-|------|------|
-| Guidelines doc | `.trellis/spec/{target}/doc.md` (section: `skill-<name>`) |
-| Code examples | `.trellis/spec/{target}/examples/skills/<name>/` |
-| Index update | `.trellis/spec/{target}/index.md` |
-
-> `{target}` = `frontend` or `backend`
-
-### # Dependencies (if needed)
-
-```bash
-# Install required dependencies (adjust for your package manager)
-npm install <package>
-# or
-pnpm add <package>
-# or
-yarn add <package>
-```
-
-### [OK] Completed Changes
-
-- [ ] Added `@@@section:skill-<name>` section to `doc.md`
-- [ ] Added index entry to `index.md`
-- [ ] Created example files in `examples/skills/<name>/`
-- [ ] Example files use `.template` suffix
-
-### # Related Guidelines
-
-- [Existing related section IDs]
-
----
-
-## 6. Optional: Create Usage Command
-
-If this skill is frequently used, create a shortcut command:
-
-```bash
-/trellis-create-command use-<skill-name> Use <skill-name> skill following project guidelines
-```
-
-## Common Skill Integration Reference
-
-| Skill | Integration Target | Examples Directory |
-|-------|-------------------|-------------------|
-| `frontend-design` | `frontend` | `examples/skills/frontend-design/` |
-| `mcp-builder` | `backend` | `examples/skills/mcp-builder/` |
-| `webapp-testing` | `frontend` | `examples/skills/webapp-testing/` |
-| `doc-coauthoring` | `.trellis/` | N/A (documentation workflow only) |
-
-## Example: Integrating `mcp-builder` Skill
-
-### Directory Structure
-
-```
-.trellis/spec/backend/
-|-- doc.md                           # Add MCP section
-|-- index.md                         # Add index entry
-+-- examples/
-    +-- skills/
-        +-- mcp-builder/
-            |-- README.md
-            |-- server.ts.template
-            |-- tools.ts.template
-            +-- types.ts.template
-```
-
-### New Section in doc.md
-
-```markdown
-@@@section:skill-mcp-builder
-## # MCP Server Development Guide
-
-### Overview
-Create LLM-callable tool services using MCP (Model Context Protocol).
-
-### Project Adaptation
-- Place services in a dedicated directory
-- Follow existing TypeScript and type definition conventions
-- Use project's logging system
-
-### Reference Examples
-See `examples/skills/mcp-builder/`
-
-@@@/section:skill-mcp-builder
-```

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

@@ -1,362 +0,0 @@
----
-description: Onboard a new team member to the Trellis AI-assisted workflow system
----
-
-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/workspace/` system captures what happened in each session - what was done, what was learned, what problems were solved. The `/trellis-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/spec/` 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 `/trellis-finish-work` command does a final holistic review.
-
----
-
-## SYSTEM STRUCTURE
-
-```
-.trellis/
-|-- .developer              # Your identity (gitignored)
-|-- workflow.md             # Complete workflow documentation
-|-- workspace/              # "AI Memory" - session history
-|   |-- index.md            # All developers' progress
-|   +-- {developer}/        # Per-developer directory
-|       |-- index.md        # Personal progress index
-|       +-- journal-N.md    # Session records (max 2000 lines)
-|-- tasks/                  # Task tracking (unified)
-|   +-- {MM}-{DD}-{slug}/   # Task directory
-|       |-- task.json       # Task metadata
-|       +-- prd.md          # Requirements doc
-|-- spec/                   # "AI Training Data" - project knowledge
-|   |-- frontend/           # Frontend conventions
-|   |-- backend/            # Backend conventions
-|   +-- guides/             # Thinking patterns
-+-- scripts/                # Automation tools
-```
-
-### Understanding spec/ 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
-
-### /trellis-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 `workspace/` (what happened before?)
-4. Identifies active features (what's in progress?)
-5. Understands current project state before making any changes
-
-**WHY THIS MATTERS**:
-- Without /trellis-start: AI is blind. It might work on wrong branch, conflict with others' work, or redo already-completed work.
-- With /trellis-start: AI knows project context, can continue where previous session left off, avoids conflicts.
-
----
-
-### /trellis-before-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. Discovers spec layers via `get_context.py --mode packages` and reads relevant guidelines
-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.
-
----
-
-### /trellis-check - 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.
-
----
-
-### /trellis-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
-
----
-
-### /trellis-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
-
----
-
-### /trellis-record-session - 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 `/trellis-start` needs this information.
-
-**WHAT IT ACTUALLY DOES**:
-1. Records session summary to `workspace/{developer}/journal-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] /trellis-start** - AI needs project context before touching code
-**[2/8] python3 ./.trellis/scripts/task.py create "Fix bug" --slug fix-bug** - Track work for future reference
-**[3/8] /trellis-before-dev** - Inject project-specific development guidelines
-**[4/8] Investigate and fix the bug** - Actual development work
-**[5/8] /trellis-check** - Re-verify code against guidelines
-**[6/8] /trellis-finish-work** - Holistic cross-layer review
-**[7/8] Human tests and commits** - Human validates before code enters repo
-**[8/8] /trellis-record-session** - Persist memory for future sessions
-
-### Example 2: Planning Session (No Code)
-
-**[1/4] /trellis-start** - Context needed even for non-coding work
-**[2/4] python3 ./.trellis/scripts/task.py create "Planning task" --slug planning-task** - Planning is valuable work
-**[3/4] Review docs, create subtask list** - Actual planning work
-**[4/4] /trellis-record-session (with --summary)** - Planning decisions must be recorded
-
-### Example 3: Code Review Fixes
-
-**[1/6] /trellis-start** - Resume context from previous session
-**[2/6] /trellis-before-dev** - Re-inject guidelines before fixes
-**[3/6] Fix each CR issue** - Address feedback with guidelines in context
-**[4/6] /trellis-check** - Verify fixes did not introduce new issues
-**[5/6] /trellis-finish-work** - Document lessons from CR
-**[6/6] Human commits, then /trellis-record-session** - Preserve CR lessons
-
-### Example 4: Large Refactoring
-
-**[1/5] /trellis-start** - Clear baseline before major changes
-**[2/5] Plan phases** - Break into verifiable chunks
-**[3/5] Execute phase by phase with /trellis-check after each** - Incremental verification
-**[4/5] /trellis-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] /trellis-start** - See if this bug was investigated before
-**[2/6] /trellis-before-dev** - Guidelines might document known gotchas
-**[3/6] Investigation** - Actual debugging work
-**[4/6] /trellis-check** - Verify debug changes do not break other things
-**[5/6] /trellis-finish-work** - Debug findings might need documentation
-**[6/6] Human commits, then /trellis-record-session** - 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 command injects project knowledge.
-3. **Check after code** - /check-* commands catch context drift.
-4. **Record everything** - /trellis-record-session 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/spec/` 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/spec/backend/*.md 2>/dev/null | wc -l
-grep -l "To be filled by the team" .trellis/spec/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/spec/` 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/spec/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/spec/` 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
-python3 ./.trellis/scripts/task.py create "Fill spec guidelines" --slug fill-spec-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 `/trellis-record-session` to record this onboard session
-2. [If guidelines empty] Start filling in `.trellis/spec/` guidelines
-3. [If guidelines ready] Start your first development task
-
-What would you like to do first?"

package/dist/templates/droid/commands/trellis/record-session.md

@@ -1,66 +0,0 @@
----
-description: Record an AI session journal after the human has tested and committed
----
-
-[!] **Prerequisite**: This command should only be used AFTER the human has tested and committed the code.
-
-**Do NOT run `git commit` directly** — the scripts below handle their own commits for `.trellis/` metadata. You only need to read git history (`git log`, `git status`, `git diff`) and run the Python scripts.
-
----
-
-## Record Work Progress
-
-### Step 1: Get Context & Check Tasks
-
-```bash
-python3 ./.trellis/scripts/get_context.py --mode record
-```
-
-[!] Archive tasks whose work is **actually done** — judge by work status, not the `status` field in task.json:
-- Code committed? → Archive it (don't wait for PR)
-- All acceptance criteria met? → Archive it
-- Don't skip archiving just because `status` still says `planning` or `in_progress`
-
-```bash
-python3 ./.trellis/scripts/task.py archive <task-name>
-```
-
-### Step 2: One-Click Add Session
-
-```bash
-# Method 1: Simple parameters
-python3 ./.trellis/scripts/add_session.py \
-  --title "Session Title" \
-  --commit "hash1,hash2" \
-  --summary "Brief summary of what was done"
-
-# Method 2: Pass detailed content via stdin
-cat << 'EOF' | python3 ./.trellis/scripts/add_session.py --stdin --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 journal-N.md
-- [OK] Auto-detects line count, creates new file if >2000 lines
-- [OK] Auto-detects Branch context (`--branch` override; otherwise Branch = task.json -> current git branch; missing values are omitted gracefully)
-- [OK] Updates index.md (Total Sessions +1, Last Active, line stats, history)
-- [OK] Auto-commits .trellis/workspace and .trellis/tasks changes
-
----
-
-## Script Command Reference
-
-| Command | Purpose |
-|---------|---------|
-| `python3 ./.trellis/scripts/get_context.py --mode record` | Get context for record-session |
-| `python3 ./.trellis/scripts/add_session.py --title "..." --commit "..."` | **One-click add session (recommended, branch auto-complete)** |
-| `python3 ./.trellis/scripts/task.py archive <name>` | Archive completed task (auto-commits) |
-| `python3 ./.trellis/scripts/task.py list` | List active tasks |