Preferences — All Agents

Master file for how any agent (librarian, coding, or otherwise) should work with Juan, across this vault and any other project. Read this before AGENTS.md or any repo-specific instructions.

Communication style

• Amazon-style: direct, concise, data-backed. Lead with the conclusion or recommendation, then supporting detail. No preamble, no filler, no restating the request back before acting.
• Prefer short paragraphs and bullet points over long prose.
• No acknowledgment phrases (“Great idea!”, “Sure, happy to help!”, etc.).
• Address Juan by name, or use “we”/”us” — this is a team effort, not an agent-serves-“the user” relationship. Never refer to him as “the user”.

• Avoid repeating a shared prefix (e.g. the same date) on consecutive lines — group under one heading/bullet and nest the varying details as indented sub-items instead:

  - 2026-08-24:
    - xxx
    - yyy
  

Boy Scout Rule

• Whenever a note is opened to make an update, review the whole note (not just the section being changed) and leave it in better shape than found — fix stale phrasing, outdated cross-references, formatting/repetition issues, etc.
• Keep such cleanups scoped and low-risk. If a fix would meaningfully restructure a section unrelated to the current task, flag it instead of making it silently.

Session start

• Begin by loading/summarizing relevant context from past interactions (prior sessions, existing notes, decisions already on file) before proposing new work. Don’t repeat questions already answered in the vault.

Asking questions

• When a decision point requires user input, present it as a set of discrete alternatives (not open-ended questions).
• For each alternative, give a concise but exhaustive pros/cons analysis — every material trade-off named, but in as few words as possible. No alternative should be presented without at least one pro and one con.

Tooling

• Avoid installing additional software unless there is no viable alternative with what’s already available. If an install is genuinely required, say so explicitly and ask first.
• Prefer vendor-provided installation methods (official install scripts, language-native package managers like pip/npm/cargo) over system package managers like Homebrew. Rationale: corporate environments may have restricted brew access, version control concerns, security/compliance considerations, and cross-platform consistency.

Naming conventions

• No personal names in titles: Project, Area, and Resource titles should not include personal names (e.g., use “Program Engineering Manager” not “Juan - Program Engineering Manager”). Personal information belongs in people: tags or body content, not titles.

Decision logging

• Every decision made during a session is documented in the respective Project, Area, or Resource file it belongs to — not left only in chat history or in a Journal note.

• Convention: append to a ## Decisions section in that PARA file, grouped under one date bullet per the anti-repetition rule above:

  ## Decisions
  - YYYY-MM-DD:
    - <decision> — rationale: <brief>; status: active|superseded
    - <decision> — rationale: <brief>; status: active|superseded
  

• If a decision doesn’t clearly belong to an existing Project/Area/ Resource, ask which one it belongs to (or whether a new one should be created) rather than defaulting to the Journal or Inbox.

Zettelkasten and note-taking

• All agents must write Zettel notes through the Librarian agent, even for simple/fast notes. This ensures Librarian guardrails and prompts are enforced consistently.
• Reuse the same Zettel note for work on the same topic within the same day. Juan works asynchronously with agents; multiple small notes for the same workflow is inefficient long-term.
  • Same topic = same note
  • Same project but different topic = different notes
  • If in doubt whether work is “same topic,” ask Juan
• Task switching in single session: When Juan switches tasks mid-session (e.g., Docker configuration → unrelated git command), create two separate Zettel notes:
  • One for the complex/substantial work (e.g., Docker configuration)
  • One for the small/simple task (e.g., git command)
  • Threshold: complexity and topic, not time
• Batching: Agents can batch multiple notes in a single Librarian call. Librarian decides how to group related notes; batching is sequential processing, not parallel creation.
• Zettel notes are immutable - once created, Zettel notes should not be updated. If information needs to be revised or expanded, create a new Zettel note and link it to the original.
• Zettel updates through Librarian - if a Zettel note requires modification (rare exception), ask the Librarian agent to handle the update to ensure proper formatting and vault conventions are maintained.

Inter-agent communication

• Use workspace ./tmp/ for file-based communication, not system /tmp/.
• Immediate use prompts: Place in ./tmp/ for messages needing immediate attention by another agent.
• Todo tasks/workflows: Place in ./tmp/target-$agent/ for pending work items (e.g., ./tmp/target-librarian/ for EOD summaries, review queues).
• Agent responsibilities: Review ./tmp/target-$agent/ at conversation start and as part of workflows; archive processed items to avoid accumulation.
• Archive pattern: Move processed items to ./tmp/target-$agent/archive/ instead of deleting. Do NOT process items in archive folders.
• Monthly cleanup: Ask user to delete archive interactions once per month. Archive folders are gitignored to prevent committing archived interactions.

MCP Tool Usage - Atlassian (Jira/Confluence)

Confluence Tools

confluence_get_page:

• Parameters: page_id (string), include_metadata (boolean, default: true), convert_to_markdown (boolean, default: true)
• Either page_id OR both title and space_key must be provided
• Does NOT support expand parameter — this is used internally by the MCP server
• Returns both content and metadata when include_metadata=true
• Some pages may return empty content due to Live Docs or other Confluence issues

confluence_search:

• Parameter: query (string) — CQL query for searching Confluence
• Example: space = "SPACEID" and type = page and title ~ "Architecture"
• Returns array of matching pages with content snippets

Important Notes:

• Corporate internal Docker image may have different tool set than open-source version
• confluence_get_page_children does NOT exist in the internal image
• If Confluence access fails, check token expiration before troubleshooting other issues
• Some Confluence pages (Live Docs) may have empty current versions despite showing content in web UI

Jira Tools

jira_get_issue:

• Parameters: issue_key (required), fields (optional), expand (optional), include (optional)
• Use include parameter to inline enrichments (remote_links, transitions, watchers, changelog, comments, worklogs)
• Example: {"issue_key": "PROJ-123", "include": "transitions,watchers,changelog"}

jira_search:

• Parameter: query (string) — JQL query for searching issues
• Example: project = PROJID and status = "In Progress"

Troubleshooting

Empty Confluence content:

• Page may be a Live Doc with empty current version
• Try confluence_search instead of direct page retrieval
• Check page version history in Confluence web UI
• Consider updating Docker image if issue persists

Token expiration:

• Atlassian tokens expire periodically
• If MCP calls fail with authentication errors, rotate tokens in ~/.codeium/windsurf/mcp_config.json
• Both Confluence and Jira tokens use the same token in current configuration