Commit f8c7fc46c4e7

Vincent Demeester <vincent@sbr.pm>
2026-06-08 15:48:17
docs(agents): soften markdown-over-HTML preference
Clarified the guideline applies to responses and docs, while allowing HTML for visual deliverables when explicitly requested. Updated the improve-codebase-architecture skill to treat markdown as a default rather than a forced convention.
main
1 parent fb3baa6
Changed files (2)
dots
agents
skills
improve-codebase-architecture
SKILL.md
pi
agent
AGENTS.md
dots/agents/skills/improve-codebase-architecture/SKILL.md
@@ -52,7 +52,8 @@ For larger codebases, dispatch parallel explorer subagents (see the
 
 ### 2. Present candidates (markdown report)
 
-Write a markdown report (per project convention — prefer markdown over HTML).
+Write a markdown report (the sensible default for a scannable review). An
+HTML report with diagrams is also fine if the user wants something more visual.
 Do NOT propose final interfaces yet. For each candidate:
 
 - **Files** — which modules are involved
dots/pi/agent/AGENTS.md
@@ -30,7 +30,7 @@ Skills from `~/.config/claude/skills/` are compatible with pi. Key skills:
 ## Stack Preferences
 
 - **Package managers:** uv for Python (NOT pip)
-- **Markdown over HTML/XML:** Use markdown formatting
+- **Markdown over HTML/XML:** Use markdown for responses and docs; HTML is fine for visual deliverables when explicitly requested
 - **Analysis vs Action:** If asked to analyze, do analysis only
 - **Org files:** NEVER edit `.org` files directly — use `emacsclient` or `org_todo` tool