@mindfoldhq/trellis 0.1.7 → 0.1.9

package/dist/templates/claude/commands/start.md

@@ -6,8 +6,6 @@ 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 Task calls executed by AI | You (AI) |
@@ -15,178 +13,268 @@ Operations in this document are categorized as:
 
 ---
 
-## Initialization
+## Initialization `[AI]`
 
-### Step 1: Understand Trellis Workflow `[AI]`
+### Step 1: Understand Development Workflow
 
 First, read the workflow guide to understand the development process:
 
 ```bash
-cat .trellis/workflow.md  # Development process, conventions, and quick start guide
+cat .trellis/workflow.md
 ```
 
-### Step 2: Get Current Status `[AI]`
+**Follow the instructions in workflow.md** - it contains:
+- Core principles (Read Before Write, Follow Standards, etc.)
+- File system structure
+- Development process
+- Best practices
+
+### Step 2: Get Current Context
 
 ```bash
 ./.trellis/scripts/get-context.sh
 ```
 
-### Step 3: Read Project Guidelines `[AI]`
+This shows: developer identity, git status, current feature (if any), backlog items.
+
+### Step 3: Read Guidelines Index
 
 ```bash
-cat .trellis/structure/frontend/index.md  # Frontend guidelines index
-cat .trellis/structure/backend/index.md   # Backend guidelines index
+cat .trellis/structure/frontend/index.md  # Frontend guidelines
+cat .trellis/structure/backend/index.md   # Backend guidelines
 cat .trellis/structure/guides/index.md    # Thinking guides
 ```
 
-### Step 4: Report Ready Status and Ask for Tasks
+### Step 4: Report and Ask
+
+Report what you learned and ask: "What would you like to work on?"
 
 ---
 
-## Working on Tasks
+## Task Classification
 
-### For Simple Tasks
+When user describes a task, classify it:
 
-1. Read relevant guidelines based on task type `[AI]`
-2. Implement the task directly `[AI]`
-3. Remind user to run `/finish-work` before committing `[USER]`
+| 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 |
+| **Development Task** | Any code change that: modifies logic, adds features, fixes bugs, touches multiple files | **Feature Workflow** |
 
-### For Complex Tasks (Multi-Step Features)
+### Decision Rule
 
-Use feature tracking and delegate to specialized agents.
+> **If in doubt, use Feature Workflow.**
+>
+> Feature Workflow ensures specs are injected to agents, resulting in higher quality code.
+> The overhead is minimal, but the benefit is significant.
 
-#### Step 1: Create Feature Directory `[AI]`
+---
 
-```bash
-FEATURE_DIR=$(./.trellis/scripts/feature.sh create "<title>" --slug <name>)
-```
+## Question / Trivial Fix
 
-#### Step 2: Initialize Context `[AI]`
+For questions or trivial fixes, work directly:
 
-```bash
-./.trellis/scripts/feature.sh init-context "$FEATURE_DIR" <type>
-# type: backend | frontend | fullstack
-```
+1. Answer question or make the fix
+2. If code was changed, remind user to run `/finish-work`
+
+---
+
+## Feature Workflow (Development Tasks)
+
+**Why this workflow?**
+- Research Agent analyzes what specs are needed
+- Specs are configured in jsonl files
+- Implement Agent receives specs via Hook injection
+- Check Agent verifies against specs
+- Result: Code that follows project conventions automatically
 
-#### Step 3: Call Research Agent to Analyze Task `[AI]`
+### Step 1: Understand the Task `[AI]`
+
+Before creating anything, understand what user wants:
+- What is the goal?
+- What type of development? (frontend / backend / fullstack)
+- Any specific requirements or constraints?
+
+If unclear, ask clarifying questions.
+
+### Step 2: Research the Codebase `[AI]`
+
+Call Research Agent to analyze:
 
 ```
 Task(
   subagent_type: "research",
-  prompt: "Analyze what development specs are needed for this task:
+  prompt: "Analyze the codebase for this task:
 
-  Task description: <user requirements>
-  Development type: <dev_type>
+  Task: <user's task description>
+  Type: <frontend/backend/fullstack>
 
-  Please:
-  1. Find relevant spec files under .trellis/structure/
-  2. Find related code modules and patterns in the project
-  3. List specific files to add to implement.jsonl, check.jsonl, debug.jsonl
+  Please find:
+  1. Relevant spec files in .trellis/structure/
+  2. Existing code patterns to follow (find 2-3 examples)
+  3. Files that will likely need modification
 
-  Output format:
-  ## implement.jsonl
-  - path: <file path>, reason: <reason>
+  Output:
+  ## Relevant Specs
+  - <path>: <why it's relevant>
 
-  ## check.jsonl
-  - path: <file path>, reason: <reason>
+  ## Code Patterns Found
+  - <pattern>: <example file path>
 
-  ## debug.jsonl
-  - path: <file path>, reason: <reason>",
+  ## Files to Modify
+  - <path>: <what change>
+
+  ## Suggested Feature Name
+  - <short-slug-name>",
   model: "opus"
 )
 ```
 
-#### Step 4: Add Specs to jsonl `[AI]`
+### Step 3: Create Feature Directory `[AI]`
+
+Based on research results:
 
 ```bash
-./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" implement "<path>" "<reason>"
-./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" check "<path>" "<reason>"
-./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" debug "<path>" "<reason>"
+FEATURE_DIR=$(./.trellis/scripts/feature.sh create "<title from research>" --slug <suggested-slug>)
+```
+
+### Step 4: Configure Context `[AI]`
+
+Initialize default context:
+
+```bash
+./.trellis/scripts/feature.sh init-context "$FEATURE_DIR" <type>
+# type: backend | frontend | fullstack
 ```
 
-Validate:
+Add specs found by Research Agent:
+
 ```bash
-./.trellis/scripts/feature.sh list-context "$FEATURE_DIR"
+# For each relevant spec and code pattern:
+./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" implement "<path>" "<reason>"
+./.trellis/scripts/feature.sh add-context "$FEATURE_DIR" check "<path>" "<reason>"
 ```
 
-#### Step 5: Create Requirements Document `[AI]`
+### Step 5: Write Requirements `[AI]`
+
+Create `prd.md` in the feature directory with:
 
-Create `prd.md` in the feature directory.
+```markdown
+# <Feature Title>
 
-#### Step 6: Start Feature `[AI]`
+## 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>
+```
+
+### Step 6: Activate Feature `[AI]`
 
 ```bash
 ./.trellis/scripts/feature.sh start "$FEATURE_DIR"
 ```
 
-#### Step 7: Delegate Work `[AI]`
+This sets `.current-feature` so hooks can inject context.
+
+### Step 7: Implement `[AI]`
+
+Call Implement Agent (specs are auto-injected by hook):
 
 ```
-Task(subagent_type: "implement", prompt: "Implement the feature described in prd.md", model: "opus")
+Task(
+  subagent_type: "implement",
+  prompt: "Implement the feature described in prd.md.
+
+  Follow all specs that have been injected into your context.
+  Run lint and typecheck before finishing.",
+  model: "opus"
+)
 ```
 
-Check quality:
+### Step 8: Check Quality `[AI]`
+
+Call Check Agent (specs are auto-injected by hook):
 
 ```
-Task(subagent_type: "check", prompt: "Check code changes and fix any issues", model: "opus")
+Task(
+  subagent_type: "check",
+  prompt: "Review all code changes against the specs.
+
+  Fix any issues you find directly.
+  Ensure lint and typecheck pass.",
+  model: "opus"
+)
 ```
 
-#### Step 8: Complete
+### Step 9: Complete `[AI]`
 
-1. Verify typecheck and lint pass `[AI]`
-2. Remind user to test
-3. Remind user to commit
-4. Remind user to run `/record-agent-flow` `[USER]`
-5. Archive feature `[AI]`:
-   ```bash
-   ./.trellis/scripts/feature.sh archive <feature-name>
-   ```
+1. Verify lint and typecheck pass
+2. Report what was implemented
+3. Remind user to:
+   - Test the changes
+   - Commit when ready
+   - Run `/record-agent-flow` to record this session
 
 ---
 
-## User Available Commands `[USER]`
+## Continuing Existing Feature
 
-The following slash commands are for users (not AI):
+If `get-context.sh` shows a current feature:
 
-| Command | Description |
-|---------|-------------|
-| `/start` | Start development session (this command) |
-| `/parallel` | Start Multi-Agent Pipeline (worktree mode) |
-| `/finish-work` | Pre-completion checklist |
-| `/record-agent-flow` | Record session progress |
-| `/check-frontend` | Check frontend code |
-| `/check-backend` | Check backend code |
+1. Read the feature's `prd.md` to understand the goal
+2. Check `feature.json` for current status and phase
+3. Ask user: "Continue working on <feature-name>?"
 
----
+If yes, resume from the appropriate step (usually Step 7 or 8).
 
-## Session End Reminder
+---
 
-**IMPORTANT**: When a task or session is completed, remind the user:
+## Commands Reference
 
-> Before ending this session, please run `/record-agent-flow` to record what we accomplished.
+### User Commands `[USER]`
 
----
+| Command | When to Use |
+|---------|-------------|
+| `/start` | Begin a session (this command) |
+| `/parallel` | Complex features needing isolated worktree |
+| `/finish-work` | Before committing changes |
+| `/record-agent-flow` | After completing a task |
 
-## AI Executed Scripts `[AI]`
+### AI Scripts `[AI]`
 
 | Script | Purpose |
 |--------|---------|
-| `feature.sh create <title> --assignee <dev> [--priority P0\|P1\|P2\|P3] [--slug <slug>]` | Create backlog + feature |
-| `feature.sh init-context <dir> <type>` | Initialize jsonl files |
-| `feature.sh add-context <dir> <jsonl> <path>` | Add specs |
-| `feature.sh start <dir>` | Set current feature |
-| `feature.sh finish` | Clear current feature |
-| `feature.sh archive <name>` | Archive feature (also deletes linked backlog) |
-| `feature.sh list` | List active features |
 | `get-context.sh` | Get session context |
+| `feature.sh create` | Create feature directory |
+| `feature.sh init-context` | Initialize jsonl files |
+| `feature.sh add-context` | Add spec to jsonl |
+| `feature.sh start` | Set current feature |
+| `feature.sh finish` | Clear current feature |
+| `feature.sh archive` | Archive completed feature |
 
-## Sub Agent Calls `[AI]`
+### Sub Agents `[AI]`
+
+| Agent | Purpose | Hook Injection |
+|-------|---------|----------------|
+| research | Analyze codebase | No (reads directly) |
+| implement | Write code | Yes (implement.jsonl) |
+| check | Review & fix | Yes (check.jsonl) |
+| debug | Fix specific issues | Yes (debug.jsonl) |
+
+---
 
-All sub agent calls use the opus model:
+## Key Principle
 
-| Agent | Purpose |
-|-------|---------|
-| research | Find specs, analyze code |
-| implement | Implement features |
-| check | Check code |
-| debug | Fix issues |
+> **Specs are injected, not remembered.**
+>
+> The Feature Workflow ensures agents receive relevant specs automatically.
+> This is more reliable than hoping the AI "remembers" conventions.

package/dist/templates/claude/hooks/session-start.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""
+Session Start Hook - Inject structured context
+
+Matcher: "startup" - only runs on normal startup (not resume/clear/compact)
+
+This hook injects:
+1. Current state (git status, current feature, backlog)
+2. Workflow guide
+3. Guidelines index (frontend/backend/guides)
+4. Session instructions (start.md)
+5. Action directive
+"""
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+
+def should_skip_injection() -> bool:
+    """
+    Determine if context injection should be skipped.
+
+    Multi-agent scripts (start.sh, plan.sh) set CLAUDE_NON_INTERACTIVE=1
+    to prevent duplicate context injection.
+    """
+    return os.environ.get("CLAUDE_NON_INTERACTIVE") == "1"
+
+
+def read_file(path: Path, fallback: str = "") -> str:
+    """Read file content, return fallback if not found."""
+    try:
+        return path.read_text(encoding="utf-8")
+    except (FileNotFoundError, PermissionError):
+        return fallback
+
+
+def run_script(script_path: Path) -> str:
+    """Run a script and return its output."""
+    try:
+        result = subprocess.run(
+            [str(script_path)],
+            capture_output=True,
+            text=True,
+            timeout=5,
+            cwd=script_path.parent.parent.parent,  # repo root
+        )
+        return result.stdout if result.returncode == 0 else "No context available"
+    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError):
+        return "No context available"
+
+
+def main():
+    # Skip injection in non-interactive mode (multi-agent scripts set CLAUDE_NON_INTERACTIVE=1)
+    if should_skip_injection():
+        sys.exit(0)
+
+    project_dir = Path(os.environ.get("CLAUDE_PROJECT_DIR", ".")).resolve()
+    trellis_dir = project_dir / ".trellis"
+    claude_dir = project_dir / ".claude"
+
+    # 1. Header
+    print("""<session-context>
+You are starting a new session in a Trellis-managed project.
+Read and follow all instructions below carefully.
+</session-context>
+""")
+
+    # 2. Current Context (dynamic)
+    print("<current-state>")
+    context_script = trellis_dir / "scripts" / "get-context.sh"
+    print(run_script(context_script))
+    print("</current-state>")
+    print()
+
+    # 3. Workflow Guide
+    print("<workflow>")
+    workflow_content = read_file(trellis_dir / "workflow.md", "No workflow.md found")
+    print(workflow_content)
+    print("</workflow>")
+    print()
+
+    # 4. Guidelines Index
+    print("<guidelines>")
+
+    print("## Frontend")
+    frontend_index = read_file(
+        trellis_dir / "structure" / "frontend" / "index.md", "Not configured"
+    )
+    print(frontend_index)
+    print()
+
+    print("## Backend")
+    backend_index = read_file(
+        trellis_dir / "structure" / "backend" / "index.md", "Not configured"
+    )
+    print(backend_index)
+    print()
+
+    print("## Guides")
+    guides_index = read_file(
+        trellis_dir / "structure" / "guides" / "index.md", "Not configured"
+    )
+    print(guides_index)
+
+    print("</guidelines>")
+    print()
+
+    # 5. Session Instructions
+    print("<instructions>")
+    start_md = read_file(claude_dir / "commands" / "start.md", "No start.md found")
+    print(start_md)
+    print("</instructions>")
+    print()
+
+    # 6. Final directive
+    print("""<ready>
+Context loaded. Wait for user's first message, then follow <instructions> to handle their request.
+</ready>""")
+
+
+if __name__ == "__main__":
+    main()

package/dist/templates/claude/settings.json

@@ -1,5 +1,17 @@
 {
   "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.py\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Task",
@@ -24,5 +36,6 @@
         ]
       }
     ]
-  }
+  },
+  "enabledPlugins": {}
 }

package/dist/templates/trellis/scripts/feature.sh

@@ -863,7 +863,7 @@ cmd_create_pr() {
   git add -A
   # Exclude agent traces and temp files
   git reset "$DIR_WORKFLOW/$DIR_PROGRESS/" 2>/dev/null || true
-  git reset .agent-log .agent-prompt .agent-runner.sh 2>/dev/null || true
+  git reset .agent-log .agent-runner.sh 2>/dev/null || true
 
   # Check if there are staged changes
   if git diff --cached --quiet 2>/dev/null; then

package/dist/templates/trellis/scripts/multi-agent/create-pr.sh

@@ -130,7 +130,7 @@ git add -A
 
 # Exclude agent traces and temp files
 git reset ".trellis/agent-traces/" 2>/dev/null || true
-git reset .agent-log .agent-prompt .agent-runner.sh 2>/dev/null || true
+git reset .agent-log .agent-runner.sh 2>/dev/null || true
 
 # Check if there are staged changes
 if git diff --cached --quiet 2>/dev/null; then

package/dist/templates/trellis/scripts/multi-agent/plan.sh

@@ -148,16 +148,6 @@ log_success "Feature directory: ${FEATURE_DIR}"
 # =============================================================================
 log_info "Step 2: Starting Plan Agent in background..."
 
-# Extract plan.md content (skip frontmatter)
-PLAN_PROMPT=$(awk '
-  BEGIN { in_frontmatter = 0; started = 0 }
-  /^---$/ {
-    if (!started) { in_frontmatter = 1; started = 1; next }
-    else if (in_frontmatter) { in_frontmatter = 0; next }
-  }
-  !in_frontmatter { print }
-' "$PLAN_MD")
-
 LOG_FILE="${FEATURE_DIR_ABS}/.plan-log"
 touch "$LOG_FILE"
 
@@ -175,26 +165,10 @@ export PLAN_REQUIREMENT="${REQUIREMENT}"
 export https_proxy="\${AGENT_HTTPS_PROXY:-}"
 export http_proxy="\${AGENT_HTTP_PROXY:-}"
 export all_proxy="\${AGENT_ALL_PROXY:-}"
+export CLAUDE_NON_INTERACTIVE=1
 
-# Create prompt content inline (no temp file needed)
-claude -p --dangerously-skip-permissions --output-format stream-json --verbose << 'PROMPT_EOF'
-# Environment Variables
-
-The following environment variables are set for this planning session:
-
-\`\`\`
-PLAN_FEATURE_NAME=${FEATURE_NAME}
-PLAN_DEV_TYPE=${DEV_TYPE}
-PLAN_FEATURE_DIR=${FEATURE_DIR}
-PLAN_REQUIREMENT=${REQUIREMENT}
-\`\`\`
-
-You can read these directly from the environment or use the values above.
-
----
-
-${PLAN_PROMPT}
-PROMPT_EOF
+# Use --agent flag to load plan agent directly
+claude -p --agent plan --dangerously-skip-permissions --output-format stream-json --verbose "Start planning for feature: ${FEATURE_NAME}"
 
 # Self-delete the runner script
 rm -f "\$0"

package/dist/templates/trellis/scripts/multi-agent/start.sh

@@ -236,16 +236,6 @@ log_success "Current feature set: ${FEATURE_DIR_RELATIVE}"
 # =============================================================================
 log_info "Step 3: Starting Claude agent..."
 
-# Extract dispatch.md content (skip frontmatter)
-DISPATCH_PROMPT=$(awk '
-  BEGIN { in_frontmatter = 0; started = 0 }
-  /^---$/ {
-    if (!started) { in_frontmatter = 1; started = 1; next }
-    else if (in_frontmatter) { in_frontmatter = 0; next }
-  }
-  !in_frontmatter { print }
-' "$DISPATCH_MD")
-
 # Update feature status
 jq '.status = "in_progress"' "$FEATURE_JSON" > "${FEATURE_JSON}.tmp"
 mv "${FEATURE_JSON}.tmp" "$FEATURE_JSON"
@@ -253,21 +243,20 @@ mv "${FEATURE_JSON}.tmp" "$FEATURE_JSON"
 cd "$WORKTREE_PATH"
 
 LOG_FILE="${WORKTREE_PATH}/.agent-log"
-PROMPT_FILE="${WORKTREE_PATH}/.agent-prompt"
 RUNNER_SCRIPT="${WORKTREE_PATH}/.agent-runner.sh"
 
 touch "$LOG_FILE"
-echo "$DISPATCH_PROMPT" > "$PROMPT_FILE"
 
-# Create runner script
+# Create runner script (uses --agent flag to load dispatch agent directly)
 cat > "$RUNNER_SCRIPT" << 'RUNNER_EOF'
 #!/bin/bash
 cd "$(dirname "$0")"
 export https_proxy="${AGENT_HTTPS_PROXY:-}"
 export http_proxy="${AGENT_HTTP_PROXY:-}"
 export all_proxy="${AGENT_ALL_PROXY:-}"
+export CLAUDE_NON_INTERACTIVE=1
 
-claude -p --dangerously-skip-permissions --output-format stream-json --verbose < .agent-prompt
+claude -p --agent dispatch --dangerously-skip-permissions --output-format stream-json --verbose "Start the pipeline"
 RUNNER_EOF
 chmod +x "$RUNNER_SCRIPT"
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindfoldhq/trellis",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "AI capabilities grow like ivy — Trellis provides the structure to guide them along a disciplined path",
   "type": "module",
   "main": "./dist/index.js",