feat: add workspace-guide skill and How to Work section in generated CLAUDE.md

Two-layer AI operational intelligence: compact decision heuristics injected
into every agent's CLAUDE.md (layer 1) and a detailed workspace-guide skill
loaded on-demand (layer 2). Supports per-agent-type conditional content.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: LastStep

catalog/skills/workspace-guide/meta.yaml

@@ -0,0 +1,3 @@
+name: workspace-guide
+description: Bonsai workspace operational guide — how to use workflows, skills, routines, sensors, and the Playbook effectively
+agents: all

catalog/skills/workspace-guide/workspace-guide.md.tmpl

@@ -0,0 +1,174 @@
+---
+tags: [skill, workspace]
+description: How to operate effectively in a Bonsai workspace — decision patterns, system mechanics, workspace evolution.
+---
+
+# Workspace Guide
+
+> Operational reference for working in a Bonsai-managed workspace. Load this skill when you need deeper understanding of how the workspace systems work together.
+
+---
+
+## How This Workspace Is Organized
+
+Your workspace follows a layered loading model:
+
+1. **Core** (`agent/Core/`) — Identity, memory, self-awareness. Loaded every session, defines who you are.
+2. **Protocols** (`agent/Protocols/`) — Session-start procedures, scope boundaries, security rules, memory management. Loaded every session after Core.
+3. **Skills** (`agent/Skills/`) — Reference standards for specific domains (coding style, API design, test strategy). Loaded on-demand when relevant.
+4. **Workflows** (`agent/Workflows/`) — Multi-step procedures for activities (planning, reviewing, auditing, reporting). Loaded on-demand when starting an activity.
+5. **Sensors** (`agent/Sensors/`) — Event-driven hooks that run automatically. You never load these manually.
+6. **Routines** (`agent/Routines/`) — Periodic maintenance tasks. Checked at session start, executed when the user approves.
+
+The **CLAUDE.md** at your workspace root is your navigation hub — it has tables listing every installed file with descriptions.
+
+---
+
+## When to Load What
+
+**Load a Workflow when:**
+- You are starting a multi-step activity: planning a feature, reviewing code, auditing security, writing a session log.
+- Follow the workflow end-to-end — it defines the complete procedure.
+- Check the "Workflows" table in CLAUDE.md for the full list.
+
+**Load a Skill when:**
+- You need reference standards for a specific domain: coding conventions, API design patterns, test strategy.
+- Load it, apply the standards, then move on. Skills are reference material, not procedures.
+- Check the "Skills" table in CLAUDE.md for the full list.
+
+**Load both when:**
+- A workflow references a skill (e.g., code-review workflow references review-checklist skill).
+- The workflow tells you when to load supporting skills.
+
+---
+
+## Using the Playbook
+
+The Playbook is your project management hub:
+
+| File | Purpose | When to use |
+|------|---------|-------------|
+| `{{ .DocsPath }}Playbook/Status.md` | Task tracker | Check at session start for assigned work |
+| `{{ .DocsPath }}Playbook/Backlog.md` | Intake queue | Add out-of-scope findings here — never fix inline |
+| `{{ .DocsPath }}Playbook/Roadmap.md` | Long-term direction | Check before proposing new features |
+| `{{ .DocsPath }}Playbook/Plans/Active/` | Implementation plans | Read your assigned plan before starting work |
+| `{{ .DocsPath }}Logs/KeyDecisionLog.md` | Decision log | Log significant architectural decisions |
+| `{{ .DocsPath }}Playbook/Standards/SecurityStandards.md` | Security constraints | Hard security rules — always applies |
+
+**Key rule:** When you discover bugs, improvements, or tech debt outside your current task, add them to `Backlog.md`. Don't fix them inline — stay focused on your assigned work.
+
+---
+{{ if .Routines }}
+## How Routines Work
+
+Routines are periodic self-maintenance tasks that keep the workspace healthy.
+
+**Lifecycle:**
+1. **Session start:** The `routine-check` sensor parses `agent/Core/routines.md`, compares `last_ran` dates against frequencies, and flags overdue routines.
+2. **User decides:** You report which routines are overdue. The user decides whether to run them now or defer.
+3. **Execution:** Read the routine's procedure file in `agent/Routines/`, follow each step.
+4. **Logging:** Append results to `{{ .DocsPath }}Logs/RoutineLog.md` with date, routine name, outcome, and notes.
+5. **Dashboard update:** Set `last_ran` to today's date in `agent/Core/routines.md`.
+
+**Rules:**
+- Every routine must be **idempotent** — safe to re-run if interrupted.
+- When validating facts, **mark stale entries as outdated** rather than deleting.
+- Never run a routine without user approval.
+
+---
+{{ end }}
+## How Sensors Work
+
+Sensors are event-driven hooks configured in `.claude/settings.json`. They fire automatically — you don't invoke them.
+
+**Event types:**
+- `SessionStart` — fires once when the session begins (e.g., inject context, check routines)
+- `PreToolUse` — fires before a tool is used (e.g., block edits outside workspace)
+- `PostToolUse` — fires after a tool is used
+- `UserPromptSubmit` — fires before each user prompt is processed (e.g., inject behavioral constraints)
+- `Stop` — fires after each response (e.g., display status bar)
+
+**Behavior types:**
+- **Blocking sensors** (scope guards) — prevent actions that violate rules. If a sensor blocks you, read the rule it's enforcing.
+- **Injecting sensors** (session-context) — add information to your context at specific events.
+- **Feedback sensors** (status-bar) — provide status information after responses.
+
+**Key rule:** Don't fight sensors. If a sensor blocks an action, it's enforcing a workspace rule. Read the sensor's description in your CLAUDE.md to understand why.
+
+---
+
+## Working with Memory
+
+`agent/Core/memory.md` is your persistent memory between sessions.
+
+**Structure:**
+- **Flags** — Temporary signals for the current work cycle (clear when resolved)
+- **Work State** — Current task, branch, what you're doing
+- **Notes** — Stable facts about the project that future sessions need
+- **Feedback** — User corrections and preferences
+- **References** — External pointers (URLs, file paths, configs)
+
+**When to write:**
+- You learn something future sessions need to know
+- The user corrects your behavior or provides preferences
+- You start or finish a task (update Work State)
+- You discover a project fact that isn't documented elsewhere
+
+**When to read:**
+- Every session start — restore context from previous sessions
+- The session-start protocol handles this automatically
+
+**Key rule:** Never use Claude Code's auto-memory system (`~/.claude/projects/*/memory/`). All persistent memory goes in `agent/Core/memory.md`.
+
+---
+
+## Evolving the Workspace
+
+The workspace is managed by the `bonsai` CLI:
+
+| Command | What it does |
+|---------|-------------|
+| `bonsai add` | Install new agents or add abilities (skills, workflows, protocols, sensors, routines) to existing agents |
+| `bonsai remove` | Remove agents or individual abilities |
+| `bonsai update` | Sync workspace after creating custom files with YAML frontmatter |
+| `bonsai guide` | View the custom files guide for creating your own abilities |
+| `bonsai list` | See what's installed in the current project |
+| `bonsai catalog` | Browse all available abilities |
+
+**Custom files:** You can create custom skills, workflows, protocols, sensors, or routines by placing files with YAML frontmatter in the appropriate `agent/` subdirectory, then running `bonsai update` to register them.
+
+---
+
+## Agent-Specific Patterns
+{{ if eq .AgentName "tech-lead" }}
+### Tech Lead Operating Model
+
+- **You plan and orchestrate** — never write application code directly. Your job is to break down features, create plans, dispatch to code agents, and review their output.
+- **Dispatch via worktrees** — each code agent works in an isolated worktree. Use the dispatch skill to send work.
+- **Check Backlog first** — before creating new work items, check `{{ .DocsPath }}Playbook/Backlog.md` for existing entries to avoid duplicates.
+- **Update Status after work** — when tasks complete, update `{{ .DocsPath }}Playbook/Status.md` and log results.
+- **Use issue-to-implementation** — for end-to-end feature delivery, follow the issue-to-implementation workflow from intake through close.
+- **Review all output** — before marking work done, review agent output against the plan for correctness, standards compliance, and security.
+{{ end }}{{ if or (eq .AgentName "backend") (eq .AgentName "frontend") (eq .AgentName "fullstack") }}
+### Code Agent Operating Model
+
+- **Read your plan first** — check `{{ .DocsPath }}Playbook/Plans/Active/` for your assigned implementation plan before writing any code. Follow it exactly.
+- **Stop if ambiguous** — if the plan is unclear or you face a decision not covered by the plan, stop and report to the tech lead. Don't guess or make architectural decisions.
+- **Stay in scope** — only modify files within your workspace boundary. The scope-guard sensor enforces this.
+- **Report completion** — use the reporting workflow to communicate results back to the tech lead.
+- **Don't make architectural decisions** — that's the tech lead's job. Your job is to implement the plan precisely.
+{{ end }}{{ if eq .AgentName "devops" }}
+### DevOps Operating Model
+
+- **Plan before apply** — never auto-approve destructive infrastructure operations. Always plan first, show the user what will change, and require explicit confirmation.
+- **Explicit confirmation for destructive ops** — any operation that deletes, replaces, or modifies live infrastructure requires the user to explicitly approve.
+- **Work with safety guards** — the iac-safety-guard sensor blocks dangerous commands. If it blocks you, the operation needs explicit approval.
+- **Stay in scope** — only modify infrastructure and deployment files within your workspace boundary.
+{{ end }}{{ if eq .AgentName "security" }}
+### Security Agent Operating Model
+
+- **Audit and report** — you read the entire codebase but only modify security-owned files. Never implement application features.
+- **Evidence-based findings** — every finding must include: specific file path, line number, and standard reference (OWASP, CWE, CVE).
+- **Only modify security-owned files** — security policies, audit reports, security configurations. Never modify application code.
+- **Use security-audit workflow** — for structured audits, follow the security-audit workflow end-to-end.
+{{ end }}

internal/catalog/catalog.go

@@ -301,7 +301,7 @@ func loadItems(fsys fs.FS, category string) []CatalogItem {
 			continue
 		}
 		for _, f := range dirEntries {
-			if !f.IsDir() && strings.HasSuffix(f.Name(), ".md") {
+			if !f.IsDir() && (strings.HasSuffix(f.Name(), ".md") || strings.HasSuffix(f.Name(), ".md.tmpl")) {
 				item.ContentPath = itemDir + "/" + f.Name()
 				break
 			}

internal/generate/generate.go

@@ -494,6 +494,62 @@ func SettingsJSON(projectRoot string, cfg *config.ProjectConfig, cat *catalog.Ca
 }
 
 
+// howToWorkLines generates the compact "How to Work" heuristics section for the workspace CLAUDE.md.
+func howToWorkLines(agentName string, docsPrefix string, hasRoutines bool, hasWorkspaceGuide bool) []string {
+	var lines []string
+	lines = append(lines,
+		"### How to Work", "",
+		"> Decision heuristics — how to use this workspace effectively.", "",
+	)
+
+	// Shared heuristics (all agents)
+	lines = append(lines,
+		fmt.Sprintf("- **Before starting work:** Check `%sPlaybook/Status.md` for assigned tasks and `%sPlaybook/Plans/Active/` for your current plan.", docsPrefix, docsPrefix),
+		"- **When to load a Workflow:** You are starting a multi-step activity (planning, reviewing, auditing). Load the matching workflow from the table above and follow it end-to-end.",
+		"- **When to load a Skill:** You need reference standards for a specific domain (coding style, API design, test strategy). Load it, use it, move on.",
+		fmt.Sprintf("- **Decision logging:** When you make or observe a significant architectural decision, append it to `%sLogs/KeyDecisionLog.md`.", docsPrefix),
+		fmt.Sprintf("- **Out-of-scope findings:** Don't fix bugs, debt, or improvements outside your current task. Add them to `%sPlaybook/Backlog.md`.", docsPrefix),
+		"- **Workspace evolution:** `bonsai add` (new abilities), `bonsai remove` (uninstall), `bonsai update` (sync custom files), `bonsai list` (see installed), `bonsai catalog` (browse available).",
+	)
+
+	// Agent-type-specific heuristics
+	switch agentName {
+	case "tech-lead":
+		lines = append(lines,
+			"- **You orchestrate, not implement.** Plan features, dispatch to code agents via worktrees, review their output. Never write application code directly.",
+			fmt.Sprintf("- **Check Backlog first:** Before creating new work items, check `%sPlaybook/Backlog.md` for existing entries.", docsPrefix),
+			fmt.Sprintf("- **After completing work:** Update `%sPlaybook/Status.md` and log results.", docsPrefix),
+		)
+	case "backend", "frontend", "fullstack":
+		lines = append(lines,
+			fmt.Sprintf("- **Plan first:** Read your assigned plan in `%sPlaybook/Plans/Active/` before writing any code. Follow it exactly.", docsPrefix),
+			"- **When stuck:** If the plan is ambiguous, stop and report — don't guess or make design decisions.",
+			"- **Stay in scope:** Only modify files within your workspace boundary.",
+		)
+	case "devops":
+		lines = append(lines,
+			"- **Plan before apply:** Never auto-approve destructive infrastructure operations. Require explicit user confirmation.",
+			"- **Stay in scope:** Only modify infrastructure and deployment files within your workspace boundary.",
+		)
+	case "security":
+		lines = append(lines,
+			"- **Audit and report.** You read the entire codebase but only modify security-owned files.",
+			"- **Evidence-based findings:** Every finding must reference a specific file, line, and standard (OWASP, CWE, CVE).",
+		)
+	}
+
+	// Workspace guide pointer
+	if hasWorkspaceGuide {
+		lines = append(lines,
+			"- **New to this workspace?** Load `agent/Skills/workspace-guide.md` for a full operational reference.",
+		)
+	}
+
+	lines = append(lines, "")
+
+	return lines
+}
+
 const (
 	bonsaiStartMarker = "<!-- BONSAI_START -->"
 	bonsaiEndMarker   = "<!-- BONSAI_END -->"
@@ -623,6 +679,17 @@ func WorkspaceClaudeMD(projectRoot string, workspaceRoot string, agentDef *catal
 			"> Sensors run automatically — they are configured in `.claude/settings.json`.", "")
 	}
 
+	// How to Work section
+	hasWorkspaceGuide := false
+	for _, s := range installed.Skills {
+		if s == "workspace-guide" {
+			hasWorkspaceGuide = true
+			break
+		}
+	}
+	htw := howToWorkLines(agentDef.Name, docsPrefix, len(installed.Routines) > 0, hasWorkspaceGuide)
+	lines = append(lines, htw...)
+
 	lines = append(lines,
 		"---", "",
 		"## Memory", "",
@@ -962,18 +1029,34 @@ func AgentWorkspace(projectRoot string, agentDef *catalog.AgentDef, installed *c
 		result.Add(r)
 	}
 
-	// 2. Skills
+	// Full template context — used by skills, sensors, and routines that have .tmpl files
+	fullCtx := &TemplateContext{
+		ProjectName:        cfg.ProjectName,
+		ProjectDescription: cfg.Description,
+		AgentName:          agentDef.Name,
+		AgentDisplayName:   agentDef.DisplayName,
+		AgentDescription:   agentDef.Description,
+		Workspace:          installed.Workspace,
+		DocsPath:           cfg.DocsPath,
+		Protocols:          installed.Protocols,
+		Skills:             installed.Skills,
+		Workflows:          installed.Workflows,
+		Routines:           installed.Routines,
+		OtherAgents:        ctx.OtherAgents,
+	}
+
+	// 2. Skills (rendered through templates if .tmpl, otherwise copied as-is)
 	for _, skillName := range installed.Skills {
 		item := cat.GetSkill(skillName)
 		if item == nil {
 			continue
 		}
-		data, err := fs.ReadFile(catFS, item.ContentPath)
+		content, err := renderContent(catFS, item.ContentPath, fullCtx)
 		if err != nil {
-			return err
+			return fmt.Errorf("skill %s: %w", skillName, err)
 		}
 		relPath, _ := filepath.Rel(projectRoot, filepath.Join(agentDir, "Skills", skillName+".md"))
-		r := writeFile(projectRoot, relPath, data, "catalog:skills/"+skillName, lock, force)
+		r := writeFile(projectRoot, relPath, content, "catalog:skills/"+skillName, lock, force)
 		result.Add(r)
 	}
 
@@ -1008,27 +1091,12 @@ func AgentWorkspace(projectRoot string, agentDef *catalog.AgentDef, installed *c
 	}
 
 	// 5. Sensors (rendered through templates)
-	sensorCtx := &TemplateContext{
-		ProjectName:        cfg.ProjectName,
-		ProjectDescription: cfg.Description,
-		AgentName:          agentDef.Name,
-		AgentDisplayName:   agentDef.DisplayName,
-		AgentDescription:   agentDef.Description,
-		Workspace:          installed.Workspace,
-		DocsPath:           cfg.DocsPath,
-		Protocols:          installed.Protocols,
-		Skills:             installed.Skills,
-		Workflows:          installed.Workflows,
-		Routines:           installed.Routines,
-		OtherAgents:        ctx.OtherAgents,
-	}
-
 	for _, sensorName := range installed.Sensors {
 		sensor := cat.GetSensor(sensorName)
 		if sensor == nil {
 			continue
 		}
-		content, err := renderContent(catFS, sensor.ContentPath, sensorCtx)
+		content, err := renderContent(catFS, sensor.ContentPath, fullCtx)
 		if err != nil {
 			return fmt.Errorf("sensor %s: %w", sensorName, err)
 		}
@@ -1044,7 +1112,7 @@ func AgentWorkspace(projectRoot string, agentDef *catalog.AgentDef, installed *c
 		if routine == nil {
 			continue
 		}
-		content, err := renderContent(catFS, routine.ContentPath, sensorCtx)
+		content, err := renderContent(catFS, routine.ContentPath, fullCtx)
 		if err != nil {
 			return fmt.Errorf("routine %s: %w", routineName, err)
 		}