@blulotus/trellis 0.7.0

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

@@ -0,0 +1,97 @@
+# 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
+- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
+- [ ] UI / command code starts casting raw payload fields directly
+
+→ 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!
+- [ ] Two files read the same untyped payload field with local casts
+- [ ] Multiple branches update the same derived state from `kind` / `action`
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+### When Verifying AI Cross-Review Results
+
+- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
+- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
+- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
+- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
+
+**Common AI reviewer false-positive patterns**:
+1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
+2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
+3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
+
+**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
+
+---
+
+## 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/workspace-index.md

@@ -0,0 +1,125 @@
+# Workspace Index
+
+> Records of all AI Agent work records across all developers
+
+---
+
+## Overview
+
+This directory tracks records for all developers working with AI Agents on this project.
+
+### File Structure
+
+```
+workspace/
+|-- index.md              # This file - main index
++-- {developer}/          # Per-developer directory
+    |-- index.md          # Personal index with session history
+    |-- tasks/         # Task files
+    |   |-- *.json        # Active tasks
+    |   +-- archive/      # Archived tasks by month
+    +-- journal-N.md     # Journal files (sequential: 1, 2, 3...)
+```
+
+---
+
+## Active Developers
+
+| Developer | Last Active | Sessions | Active File |
+|-----------|-------------|----------|-------------|
+| (none yet) | - | - | - |
+
+---
+
+## Getting Started
+
+### For New Developers
+
+Run the initialization script:
+
+```bash
+python3 ./.trellis/scripts/init_developer.py <your-name>
+```
+
+This will:
+1. Create your identity file (gitignored)
+2. Create your progress directory
+3. Create your personal index
+4. Create initial journal file
+
+### For Returning Developers
+
+1. Get your developer name:
+   ```bash
+   python3 ./.trellis/scripts/get_developer.py
+   ```
+
+2. Read your personal index:
+   ```bash
+   cat .trellis/workspace/$(python3 ./.trellis/scripts/get_developer.py)/index.md
+   ```
+
+---
+
+## Guidelines
+
+### Journal File Rules
+
+- **Max 2000 lines** per journal file
+- When limit is reached, create `journal-{N+1}.md`
+- Update your personal `index.md` when creating new files
+
+### Session Record Format
+
+Each session should include:
+- Summary: One-line description
+- Branch: Which branch the work was done on
+- Main Changes: What was modified
+- Git Commits: Commit hashes and messages
+- Next Steps: What to do next
+
+---
+
+## Session Template
+
+Use this template when recording sessions:
+
+```markdown
+## Session {N}: {Title}
+
+**Date**: YYYY-MM-DD
+**Task**: {task-name}
+**Branch**: `{branch-name}`
+
+### Summary
+
+{One-line summary}
+
+### Main Changes
+
+- {Change 1}
+- {Change 2}
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `abc1234` | {commit message} |
+
+### Testing
+
+- [OK] {Test result}
+
+### Status
+
+[OK] **Completed** / # **In Progress** / [P] **Blocked**
+
+### Next Steps
+
+- {Next step 1}
+- {Next step 2}
+```
+
+---
+
+**Language**: All documentation must be written in **English**.

package/dist/templates/markdown/worktree.yaml.txt

@@ -0,0 +1,58 @@
+# Worktree Configuration for Multi-Agent Pipeline
+# Used for worktree initialization in multi-agent workflows
+#
+# All paths are relative to project root
+
+#-------------------------------------------------------------------------------
+# Paths
+#-------------------------------------------------------------------------------
+
+# Worktree storage directory (relative to project root)
+# Recommended: keep worktrees outside the main repo to avoid conflicts
+worktree_dir: ../<project-name>-worktrees
+
+#-------------------------------------------------------------------------------
+# Files to Copy
+#-------------------------------------------------------------------------------
+
+# Files to copy to each worktree (each worktree needs independent copy)
+# These files contain sensitive info or need worktree-independent config
+copy:
+  # Environment variables (uncomment and customize as needed)
+  # - .env
+  # - .env.local
+  # Workflow config
+  - .trellis/.developer
+
+#-------------------------------------------------------------------------------
+# Post-Create Hooks
+#-------------------------------------------------------------------------------
+
+# Commands to run after creating worktree
+# Executed in worktree directory, in order, abort on failure
+post_create:
+  # Install dependencies (uncomment based on your package manager)
+  # - npm install
+  # - pnpm install --frozen-lockfile
+  # - yarn install --frozen-lockfile
+  # - pip install -r requirements.txt
+  # - bundle install
+  # - cargo build
+
+#-------------------------------------------------------------------------------
+# Pre-Merge Checks
+#-------------------------------------------------------------------------------
+
+# Pre-merge validation (used by create_pr.py)
+pre_merge:
+  # Type checking (uncomment based on your setup)
+  # - npm run typecheck
+  # - pnpm typecheck
+  # - mypy .
+  # Linting
+  # - npm run lint
+  # - pnpm lint
+  # - ruff check .
+  # Testing
+  # - npm test
+  # - pytest

package/dist/templates/omp/agents/trellis-check.md

@@ -0,0 +1,41 @@
+---
+name: trellis-check
+description: |
+  Code quality check expert. Reviews changes against Trellis specs, fixes issues directly, and verifies quality gates.
+tools: read, write, edit, bash, find, search, ast_grep, lsp
+---
+
+# Check Agent
+
+You are the Check Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-check` sub-agent that the main session dispatched.
+Do the review and fixes directly.
+
+- Do NOT spawn another `trellis-check` or `trellis-implement` sub-agent via the `task` tool.
+- If injected workflow-state breadcrumbs say to dispatch `trellis-implement` / `trellis-check`,
+  treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more implementation work
+  is needed, report that recommendation instead of spawning.
+
+## Core Responsibilities
+
+1. Inspect the current git diff.
+2. Read and follow the spec and research files listed in the task's `check.jsonl`.
+3. Review all changed code against the task PRD and project specs, then verify the red-evidence trail: every completed `implement.md` slice records the red output it started from, and for `meta.kind=bug` the Phase 1.2 repro command has been re-run green against the full scenario. A slice claiming green with no recorded red is a finding, not a pass.
+4. Fix issues directly when they are within scope.
+5. Run the relevant lint, typecheck, and focused tests for the touched code.
+
+## Review Priorities
+
+- Behavioral regressions and missing requirements.
+- Spec or platform contract violations.
+- Missing or weak tests for logic changes.
+- Cross-platform path, command, and encoding assumptions.
+
+## Output
+
+Report findings fixed, files changed, and verification results.
+If no issues remain, say that clearly.

package/dist/templates/omp/agents/trellis-implement.md

@@ -0,0 +1,55 @@
+---
+name: trellis-implement
+description: |
+  Code implementation expert. Understands Trellis specs and requirements, then implements features. No git commit allowed.
+tools: read, write, edit, bash, find, search, ast_grep, lsp
+model: pi/task
+---
+
+# Implement Agent
+
+You are the Implement Agent in the Trellis workflow.
+
+## Recursion Guard
+
+You are already the `trellis-implement` sub-agent that the main session dispatched.
+Do the implementation work directly.
+
+- Do NOT spawn another `trellis-implement` or `trellis-check` sub-agent via the `task` tool.
+- If injected workflow-state breadcrumbs say to dispatch `trellis-implement` / `trellis-check`,
+  treat that as a main-session instruction that is already satisfied by your current role.
+- Only the main session may dispatch Trellis implement/check agents. If more parallel work
+  is needed, report that recommendation instead of spawning.
+
+## Core Responsibilities
+
+1. Understand the active task requirements.
+2. Read and follow the spec and research files listed in the task's `implement.jsonl`.
+3. Implement the requested change red-before-green, one `implement.md` slice at a time, using existing project patterns.
+4. Run the relevant lint, typecheck, and focused tests for the touched code.
+5. Report files changed and verification results.
+
+## Red Before Green
+
+Walk the `implement.md` slice checklist one slice at a time. Per slice: write the test at a seam confirmed in `design.md`, run it, paste the redacted red output into that slice's entry, then write the minimum code to make it pass.
+
+- Do not invent a seam that is not in `design.md` — a missing seam is a planning defect. Report it instead of improvising one.
+- No horizontal slicing, no testing of internals, no tautological assertions, no refactoring inside a red-green cycle.
+- `meta.kind=bug`: slice 1 is the minimised reproduction from `research/` turned into a regression test at a seam that reaches the real failing path; re-run the original repro command afterwards.
+- `meta.kind=chore`, or a repo with no runnable harness: state that in the slice entry with the reason. Never skip the cycle silently.
+- Load the `trellis-tdd` skill for the full contract.
+
+## Forbidden Operations
+
+Do not run:
+- `git commit`
+- `git push`
+- `git merge`
+
+## Working Rules
+
+- Read adjacent code and tests before editing.
+- Keep changes scoped to the task.
+- Do not revert unrelated user or concurrent changes.
+- Fix root causes rather than masking symptoms.
+- Prefer existing local helpers and platform patterns over new abstractions.

package/dist/templates/omp/agents/trellis-research.md

@@ -0,0 +1,30 @@
+---
+name: trellis-research
+description: |
+  Code and technical research expert. Finds relevant files, patterns, docs,
+  and persists findings to the current task's research/ directory.
+tools: read, write, bash, find, search, web_search
+model: pi/task
+---
+
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+Persist every finding to a file. Chat context is temporary; files under the task
+directory survive compaction and handoff.
+
+## Core Responsibilities
+
+1. Resolve the active task with `python3 ./.trellis/scripts/task.py current --source`.
+2. Create `<task-dir>/research/` when it does not exist.
+3. Search internal code, specs, and relevant external documentation.
+4. Write each distinct topic to `<task-dir>/research/<topic-slug>.md`.
+5. Report only file paths and concise summaries to the caller.
+
+## Scope Limits
+
+Write only under the current task's `research/` directory.
+Do not edit code, specs, platform config, or task files outside research artifacts.