@jahanxu/trellis 0.4.1

package/dist/templates/cursor/commands/trellis-start.md

@@ -0,0 +1,366 @@
+# Start Session
+
+Initialize your AI development session and begin working on tasks.
+
+---
+
+## Operation Types
+
+Operations in this document are categorized as:
+
+| Marker | Meaning | Executor |
+|--------|---------|----------|
+| `[AI]` | Bash scripts or file reads executed by AI | You (AI) |
+| `[USER]` | Slash commands executed by user | User |
+
+---
+
+## Initialization
+
+### Step 1: Understand Trellis Workflow `[AI]`
+
+First, read the workflow guide to understand the development process:
+
+```bash
+cat .trellis/workflow.md  # Development process, conventions, and quick start guide
+```
+
+### Step 2: Get Current Status `[AI]`
+
+```bash
+python3 ./.trellis/scripts/get_context.py
+```
+
+This returns:
+- Developer identity
+- Git status (branch, uncommitted changes)
+- Recent commits
+- Active tasks
+- Journal file status
+
+### Step 3: Read Project Code-Spec Index `[AI]`
+
+Based on the upcoming task, read appropriate code-spec docs:
+
+**For Frontend Work**:
+```bash
+cat .trellis/spec/frontend/index.md
+```
+
+**For Backend Work**:
+```bash
+cat .trellis/spec/backend/index.md
+```
+
+**For Cross-Layer Features**:
+```bash
+cat .trellis/spec/guides/index.md
+cat .trellis/spec/guides/cross-layer-thinking-guide.md
+```
+
+### Step 4: Check Active Tasks `[AI]`
+
+```bash
+python3 ./.trellis/scripts/task.py list
+```
+
+If continuing previous work, review the task file.
+
+### Step 5: Report Ready Status and Ask for Tasks
+
+Output a summary:
+
+```markdown
+## Session Initialized
+
+| Item | Status |
+|------|--------|
+| Developer | {name} |
+| Branch | {branch} |
+| Uncommitted | {count} file(s) |
+| Journal | {file} ({lines}/2000 lines) |
+| Active Tasks | {count} |
+
+Ready for your task. What would you like to work on?
+```
+
+---
+
+## Task Classification
+
+When user describes a task, classify it:
+
+| Type | Criteria | Workflow |
+|------|----------|----------|
+| **Question** | User asks about code, architecture, or how something works | Answer directly |
+| **Trivial Fix** | Typo fix, comment update, single-line change, < 5 minutes | Direct Edit |
+| **Simple Task** | Clear goal, 1-2 files, well-defined scope | Quick confirm → Task Workflow |
+| **Complex Task** | Vague goal, multiple files, architectural decisions | **Brainstorm → Task Workflow** |
+
+### Decision Rule
+
+> **If in doubt, use Brainstorm + Task Workflow.**
+>
+> Task Workflow ensures code-specs are injected to the right context, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
+
+---
+
+## Question / Trivial Fix
+
+For questions or trivial fixes, work directly:
+
+1. Answer question or make the fix
+2. If code was changed, remind user to run `/trellis-finish-work`
+
+---
+
+## Simple Task
+
+For simple, well-defined tasks:
+
+1. Quick confirm: "I understand you want to [goal]. Ready to proceed?"
+2. If yes, proceed to **Task Workflow Phase 1 Path B** (create task, write PRD, then research)
+3. If no, clarify and confirm again
+
+---
+
+## Complex Task - Brainstorm First
+
+For complex or vague tasks, use `/trellis-brainstorm` first to clarify requirements before implementation.
+
+Summary:
+
+1. **Acknowledge and classify** - State your understanding
+2. **Create task directory** - Track evolving requirements in `prd.md`
+3. **Ask questions one at a time** - Update PRD after each answer
+4. **Propose approaches** - For architectural decisions
+5. **Confirm final requirements** - Get explicit approval
+6. **Proceed to Task Workflow** - With clear requirements in PRD
+
+---
+
+## Task Workflow (Development Tasks)
+
+**Why this workflow?**
+- Run a dedicated research pass before coding
+- Configure specs in jsonl context files
+- Implement using injected context
+- Verify with a separate check pass
+- Result: Code that follows project conventions automatically
+
+### Overview: Two Entry Points
+
+```
+From Brainstorm (Complex Task):
+  PRD confirmed → Research → Configure Context → Activate → Implement → Check → Complete
+
+From Simple Task:
+  Confirm → Create Task → Write PRD → Research → Configure Context → Activate → Implement → Check → Complete
+```
+
+**Key principle: Research happens AFTER requirements are clear (PRD exists).**
+
+---
+
+### Phase 1: Establish Requirements
+
+#### Path A: From Brainstorm (skip to Phase 2)
+
+PRD and task directory already exist from brainstorm. Skip directly to Phase 2.
+
+#### Path B: From Simple Task
+
+**Step 1: Confirm Understanding** `[AI]`
+
+Quick confirm:
+- What is the goal?
+- What type of development? (frontend / backend / fullstack)
+- Any specific requirements or constraints?
+
+If unclear, ask clarifying questions.
+
+**Step 2: Create Task Directory** `[AI]`
+
+```bash
+TASK_DIR=$(python3 ./.trellis/scripts/task.py create "<title>" --slug <name>)
+```
+
+**Step 3: Write PRD** `[AI]`
+
+Create `prd.md` in the task directory with:
+
+```markdown
+# <Task Title>
+
+## Goal
+<What we're trying to achieve>
+
+## Requirements
+- <Requirement 1>
+- <Requirement 2>
+
+## Acceptance Criteria
+- [ ] <Criterion 1>
+- [ ] <Criterion 2>
+
+## Technical Notes
+<Any technical decisions or constraints>
+```
+
+---
+
+### Phase 2: Prepare for Implementation (shared)
+
+> Both paths converge here. PRD and task directory must exist before proceeding.
+
+**Step 4: Code-Spec Depth Check** `[AI]`
+
+If the task touches infra or cross-layer contracts, do not start implementation until code-spec depth is defined.
+
+Trigger this requirement when the change includes any of:
+- New or changed command/API signatures
+- Database schema or migration changes
+- Infra integrations (storage, queue, cache, secrets, env contracts)
+- Cross-layer payload transformations
+
+Must-have before proceeding:
+- [ ] Target code-spec files to update are identified
+- [ ] Concrete contract is defined (signature, fields, env keys)
+- [ ] Validation and error matrix is defined
+- [ ] At least one Good/Base/Bad case is defined
+
+**Step 5: Research the Codebase** `[AI]`
+
+Based on the confirmed PRD, run a focused research pass and produce:
+
+1. Relevant spec files in `.trellis/spec/`
+2. Existing code patterns to follow (2-3 examples)
+3. Files that will likely need modification
+
+Use this output format:
+
+```markdown
+## Relevant Specs
+- <path>: <why it's relevant>
+
+## Code Patterns Found
+- <pattern>: <example file path>
+
+## Files to Modify
+- <path>: <what change>
+```
+
+**Step 6: Configure Context** `[AI]`
+
+Initialize default context:
+
+```bash
+python3 ./.trellis/scripts/task.py init-context "$TASK_DIR" <type>
+# type: backend | frontend | fullstack
+```
+
+Add specs found in your research pass:
+
+```bash
+# For each relevant spec and code pattern:
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" implement "<path>" "<reason>"
+python3 ./.trellis/scripts/task.py add-context "$TASK_DIR" check "<path>" "<reason>"
+```
+
+**Step 7: Activate Task** `[AI]`
+
+```bash
+python3 ./.trellis/scripts/task.py start "$TASK_DIR"
+```
+
+This sets `.current-task` so hooks can inject context.
+
+---
+
+### Phase 3: Execute (shared)
+
+**Step 8: Implement** `[AI]`
+
+Implement the task described in `prd.md`.
+
+- Follow all specs injected into implement context
+- Keep changes scoped to requirements
+- Run lint and typecheck before finishing
+
+**Step 9: Check Quality** `[AI]`
+
+Run a quality pass against check context:
+
+- Review all code changes against the specs
+- Fix issues directly
+- Ensure lint and typecheck pass
+
+**Step 10: Complete** `[AI]`
+
+1. Verify lint and typecheck pass
+2. Report what was implemented
+3. Remind user to:
+   - Test the changes
+   - Commit when ready
+   - Run `/trellis-record-session` to record this session
+
+---
+
+## User Available Commands `[USER]`
+
+The following slash commands are for users (not AI):
+
+| Command | Description |
+|---------|-------------|
+| `/trellis-start` | Start development session (this command) |
+| `/trellis-brainstorm` | Clarify vague requirements before implementation |
+| `/trellis-before-frontend-dev` | Read frontend guidelines |
+| `/trellis-before-backend-dev` | Read backend guidelines |
+| `/trellis-check-frontend` | Check frontend code |
+| `/trellis-check-backend` | Check backend code |
+| `/trellis-check-cross-layer` | Cross-layer verification |
+| `/trellis-finish-work` | Pre-commit checklist |
+| `/trellis-record-session` | Record session progress |
+
+---
+
+## AI Executed Scripts `[AI]`
+
+| Script | Purpose |
+|--------|---------|
+| `python3 ./.trellis/scripts/task.py create "<title>" [--slug <name>]` | Create task directory |
+| `python3 ./.trellis/scripts/task.py list` | List active tasks |
+| `python3 ./.trellis/scripts/task.py archive <name>` | Archive task |
+| `python3 ./.trellis/scripts/get_context.py` | Get session context |
+
+---
+
+## Platform Detection
+
+Trellis auto-detects your platform based on config directories. For Cursor users, ensure detection works correctly:
+
+| Condition | Detected Platform |
+|-----------|-------------------|
+| Only `.cursor/` exists | `cursor` ✅ |
+| Both `.cursor/` and `.claude/` exist | `claude` (default) |
+
+If auto-detection fails, set manually:
+
+```bash
+export TRELLIS_PLATFORM=cursor
+```
+
+Or prefix commands:
+
+```bash
+TRELLIS_PLATFORM=cursor python3 ./.trellis/scripts/task.py list
+```
+
+---
+
+## Session End Reminder
+
+**IMPORTANT**: When a task or session is completed, remind the user:
+
+> Before ending this session, please run `/trellis-record-session` to record what we accomplished.

package/dist/templates/cursor/commands/trellis-update-spec.md

@@ -0,0 +1,354 @@
+# Update Code-Spec - Capture Executable Contracts
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant code-spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## Code-Spec First Rule (CRITICAL)
+
+In this project, "spec" for implementation work means **code-spec**:
+- Executable contracts (not principle-only text)
+- Concrete signatures, payload fields, env keys, and boundary behavior
+- Testable validation/error behavior
+
+If the change touches infra or cross-layer contracts, code-spec depth is mandatory.
+
+### Mandatory Triggers
+
+Apply code-spec depth when the change includes any of:
+- New/changed command or API signature
+- Cross-layer request/response contract change
+- Database schema/migration change
+- Infra integration (storage, queue, cache, secrets, env wiring)
+
+### Mandatory Output (7 Sections)
+
+For triggered tasks, include all sections below:
+1. Scope / Trigger
+2. Signatures (command/API/DB)
+3. Contracts (request/response/env)
+4. Validation & Error Matrix
+5. Good/Base/Bad Cases
+6. Tests Required (with assertion points)
+7. Wrong vs Correct (at least one pair)
+
+---
+
+## When to Update Code-Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Implemented a feature** | Added template download with giget | Relevant `backend/` or `frontend/` file |
+| **Made a design decision** | Used type field + mapping table for extensibility | Relevant code-spec + "Design Decisions" section |
+| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
+| **Discovered a pattern** | Found a better way to structure code | Relevant `backend/` or `frontend/` file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant code-spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
+| **New thinking trigger** | "Don't forget to check X before doing Y" | `guides/*.md` (as a checklist item, not detailed rules) |
+
+**Key Insight**: Code-spec updates are NOT just for problems. Every feature implementation contains design decisions and contracts that future AI/developers need to execute safely.
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── backend/           # Backend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+├── frontend/          # Frontend coding standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking checklists (NOT coding specs!)
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+### CRITICAL: Code-Spec vs Guide - Know the Difference
+
+| Type | Location | Purpose | Content Style |
+|------|----------|---------|---------------|
+| **Code-Spec** | `backend/*.md`, `frontend/*.md` | Tell AI "how to implement safely" | Signatures, contracts, matrices, cases, test points |
+| **Guide** | `guides/*.md` | Help AI "what to think about" | Checklists, questions, pointers to specs |
+
+**Decision Rule**: Ask yourself:
+
+- "This is **how to write** the code" → Put in `backend/` or `frontend/`
+- "This is **what to consider** before writing" → Put in `guides/`
+
+**Example**:
+
+| Learning | Wrong Location | Correct Location |
+|----------|----------------|------------------|
+| "Use `reconfigure()` not `TextIOWrapper` for Windows stdout" | ❌ `guides/cross-platform-thinking-guide.md` | ✅ `backend/script-conventions.md` |
+| "Remember to check encoding when writing cross-platform code" | ❌ `backend/script-conventions.md` | ✅ `guides/cross-platform-thinking-guide.md` |
+
+**Guides should be short checklists that point to specs**, not duplicate the detailed rules.
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **Design Decision** | Why we chose approach X over Y | Add to "Design Decisions" section |
+| **Project Convention** | How we do X in this project | Add to relevant section with examples |
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Code-Spec
+
+Before editing, read the current code-spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Contracts**: Add signatures, payload fields, and error behavior
+4. **Show Code**: Add code snippets for key patterns
+5. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the code-spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Mandatory Template for Infra/Cross-Layer Work
+
+```markdown
+## Scenario: <name>
+
+### 1. Scope / Trigger
+- Trigger: <why this requires code-spec depth>
+
+### 2. Signatures
+- Backend command/API/DB signature(s)
+
+### 3. Contracts
+- Request fields (name, type, constraints)
+- Response fields (name, type, constraints)
+- Environment keys (required/optional)
+
+### 4. Validation & Error Matrix
+- <condition> -> <error>
+
+### 5. Good/Base/Bad Cases
+- Good: ...
+- Base: ...
+- Bad: ...
+
+### 6. Tests Required
+- Unit/Integration/E2E with assertion points
+
+### 7. Wrong vs Correct
+#### Wrong
+...
+#### Correct
+...
+```
+
+### Adding a Design Decision
+
+```markdown
+### Design Decision: [Decision Name]
+
+**Context**: What problem were we solving?
+
+**Options Considered**:
+1. Option A - brief description
+2. Option B - brief description
+
+**Decision**: We chose Option X because...
+
+**Example**:
+\`\`\`typescript
+// How it's implemented
+code example
+\`\`\`
+
+**Extensibility**: How to extend this in the future...
+```
+
+### Adding a Project Convention
+
+```markdown
+### Convention: [Convention Name]
+
+**What**: Brief description of the convention.
+
+**Why**: Why we do it this way in this project.
+
+**Example**:
+\`\`\`typescript
+// How to follow this convention
+code example
+\`\`\`
+
+**Related**: Links to related conventions or specs.
+```
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What did you learn or decide?**
+   - Design decision (why X over Y)
+   - Project convention (how we do X)
+   - Non-obvious behavior (gotcha)
+   - Better approach (pattern)
+
+3. **Would future AI/developers need to know this?**
+   - To understand how the code works → Yes, update spec
+   - To maintain or extend the feature → Yes, update spec
+   - To avoid repeating mistakes → Yes, update spec
+   - Purely one-off implementation detail → Maybe skip
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your code-spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Did you include executable signatures/contracts?
+- [ ] Did you include validation and error matrix?
+- [ ] Did you include Good/Base/Bad cases?
+- [ ] Did you include required tests with assertion points?
+- [ ] Is it in the right code-spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /trellis-update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis-break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/trellis-break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis-update-spec` - Actually makes the updates (this command)
+- `/trellis-finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Code-specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the implementation contract clearer.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails