feat: add entry templates for rich learnings and decisions

- Add .context/templates/ with learning.md and decision.md templates
- Templates are copied during ctx init for --file usage
- Document rich entry workflow in AGENT_PLAYBOOK.md
- Completes Phase 13: Rich Context Entries

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

Author: josealekhine

.context/AGENT_PLAYBOOK.md

@@ -167,6 +167,65 @@ For complex sessions (architecture, debugging), include:
 | Completed task              | Mark [x] in TASKS.md  |
 | Had important discussion    | Save to sessions/     |
 
+## Rich Entries with Templates
+
+For complex learnings or decisions that need more structure, use the `--file` flag
+with entry templates located in `.context/templates/`.
+
+### Available Templates
+
+| Template | Structure | Use When |
+|----------|-----------|----------|
+| `learning.md` | Context → Lesson → Application | Documenting complex discoveries with actionable guidance |
+| `decision.md` | Context → Options → Decision → Rationale → Consequences | Recording architectural choices with full reasoning |
+
+### Workflow: Inline vs File
+
+**Use inline** (`ctx add learning "message"`) for:
+- Quick, simple observations
+- One-liner tips or gotchas
+- Discoveries that need no context
+
+**Use --file** (`ctx add learning --file entry.md`) for:
+- Multi-paragraph explanations
+- Decisions requiring trade-off analysis
+- Learnings that need context and application guidance
+
+### Example: Rich Learning
+
+```bash
+# Copy template
+cp .context/templates/learning.md /tmp/my-learning.md
+
+# Edit with your content
+# Then add:
+ctx add learning --file /tmp/my-learning.md
+```
+
+### Example: Rich Decision
+
+```bash
+# Copy template
+cp .context/templates/decision.md /tmp/my-decision.md
+
+# Fill in:
+# - Context: What situation prompted this?
+# - Options: What alternatives were considered?
+# - Decision: What was chosen?
+# - Rationale: Why this choice?
+# - Consequences: What changes as a result?
+
+ctx add decision --file /tmp/my-decision.md
+```
+
+### Stdin Support
+
+You can also pipe content directly:
+```bash
+echo "Quick learning from exploration" | ctx add learning
+cat detailed-analysis.md | ctx add decision
+```
+
 ## Before Session Ends
 
 **CRITICAL**: Before the user ends the session, offer to save context:

.context/TASKS.md

@@ -141,6 +141,6 @@
 ### Phase 13: Rich Context Entries `#priority:medium` `#area:cli`
 - [x] Add --file flag to ctx add — read entry content from a file instead of CLI arg
 - [x] Add stdin support to ctx add — if no content arg and stdin is pipe, read from stdin
-- [ ] Create learning template with Context/Lesson/Application structure for --file usage
-- [ ] Create decision template with Context/Options/Decision/Rationale structure for --file usage
-- [ ] Document rich entry workflow in AGENT_PLAYBOOK.md — explain when/how agents should use --file vs inline
+- [x] Create learning template with Context/Lesson/Application structure for --file usage
+- [x] Create decision template with Context/Options/Decision/Rationale structure for --file usage
+- [x] Document rich entry workflow in AGENT_PLAYBOOK.md — explain when/how agents should use --file vs inline

internal/cli/init.go

@@ -151,6 +151,12 @@ func runInit(cmd *cobra.Command, _ []string) error {
 
 	cmd.Printf("\n%s initialized in %s/\n", green("Context"), contextDir)
 
+	// Create entry templates in .context/templates/
+	if err := createEntryTemplates(cmd, contextDir, initForce); err != nil {
+		// Non-fatal: warn but continue
+		cmd.Printf("  %s Entry templates: %v\n", color.YellowString("⚠"), err)
+	}
+
 	// Create IMPLEMENTATION_PLAN.md in project root (orchestrator directive)
 	if err := createImplementationPlan(cmd, initForce); err != nil {
 		// Non-fatal: warn but continue
@@ -493,6 +499,47 @@ func updateCtxSection(cmd *cobra.Command, existing string, newTemplate []byte, g
 	return nil
 }
 
+// createEntryTemplates creates .context/templates/ with entry templates for rich entries.
+// These templates help users format detailed learnings and decisions using --file flag.
+func createEntryTemplates(cmd *cobra.Command, contextDir string, force bool) error {
+	green := color.New(color.FgGreen).SprintFunc()
+	yellow := color.New(color.FgYellow).SprintFunc()
+
+	templatesDir := filepath.Join(contextDir, "templates")
+	if err := os.MkdirAll(templatesDir, 0755); err != nil {
+		return fmt.Errorf("failed to create %s: %w", templatesDir, err)
+	}
+
+	// Get list of entry templates
+	entryTemplates, err := templates.ListEntryTemplates()
+	if err != nil {
+		return fmt.Errorf("failed to list entry templates: %w", err)
+	}
+
+	for _, name := range entryTemplates {
+		targetPath := filepath.Join(templatesDir, name)
+
+		// Check if file exists and --force not set
+		if _, err := os.Stat(targetPath); err == nil && !force {
+			cmd.Printf("  %s templates/%s (exists, skipped)\n", yellow("○"), name)
+			continue
+		}
+
+		content, err := templates.GetEntryTemplate(name)
+		if err != nil {
+			return fmt.Errorf("failed to read entry template %s: %w", name, err)
+		}
+
+		if err := os.WriteFile(targetPath, content, 0644); err != nil {
+			return fmt.Errorf("failed to write %s: %w", targetPath, err)
+		}
+
+		cmd.Printf("  %s templates/%s\n", green("✓"), name)
+	}
+
+	return nil
+}
+
 // checkCtxInPath verifies that ctx is available in PATH.
 // The hooks use "ctx" expecting it to be in PATH, so init should fail
 // if the user hasn't installed ctx globally yet.

internal/templates/embed.go

@@ -9,7 +9,7 @@ package templates
 
 import "embed"
 
-//go:embed *.md
+//go:embed *.md entry-templates/*.md
 var FS embed.FS
 
 // GetTemplate reads a template file by name from the embedded filesystem.
@@ -32,3 +32,24 @@ func ListTemplates() ([]string, error) {
 	}
 	return names, nil
 }
+
+// ListEntryTemplates returns available entry template file names.
+func ListEntryTemplates() ([]string, error) {
+	entries, err := FS.ReadDir("entry-templates")
+	if err != nil {
+		return nil, err
+	}
+
+	names := make([]string, 0, len(entries))
+	for _, entry := range entries {
+		if !entry.IsDir() {
+			names = append(names, entry.Name())
+		}
+	}
+	return names, nil
+}
+
+// GetEntryTemplate reads an entry template by name.
+func GetEntryTemplate(name string) ([]byte, error) {
+	return FS.ReadFile("entry-templates/" + name)
+}

internal/templates/entry-templates/decision.md

@@ -0,0 +1,15 @@
+## [Decision Title]
+
+**Status**: Accepted | Proposed | Superseded | Deprecated
+
+**Context**: [What situation prompted this decision? What problem are we solving?]
+
+**Options Considered**:
+1. **Option A**: [Description] - Pros: [...] Cons: [...]
+2. **Option B**: [Description] - Pros: [...] Cons: [...]
+
+**Decision**: [What was decided?]
+
+**Rationale**: [Why was this the right choice? What trade-offs were made?]
+
+**Consequences**: [What are the implications? What changes as a result?]

internal/templates/entry-templates/learning.md

@@ -0,0 +1,9 @@
+### [Title - What was learned]
+
+**Discovered**: [Date/Session context]
+
+**Context**: [What situation prompted this discovery? What were you trying to do?]
+
+**Lesson**: [What did you learn? Be specific and actionable.]
+
+**Application**: [How should this be applied going forward? When does this matter?]