resolutionflow/CLAUDE-SETUP.md

Claude Code Setup Reference for Apoklisis

This document catalogs all tools, plugins, and MCP servers available to Claude Code when developing Apoklisis, along with guidelines for their effective use.

Last Updated: 2026-01-27 Project: Apoklisis Working Directory: c:\Dev\Projects\Apoklisis Platform: Windows (win32) IDE: VSCode with Claude Code extension

---

Core Built-In Tools

File Operations

Read

• Purpose: Read file contents from the filesystem
• Capabilities:
  • Reads up to 2000 lines by default
  • Supports offset/limit for large files
  • Can read images (PNG, JPG), PDFs, and Jupyter notebooks
  • Returns content with line numbers
• When to use: Always read files before editing them; use for examining code, configs, or documentation

Edit

• Purpose: Perform exact string replacements in files
• Capabilities:
  • Replaces old_string with new_string
  • Supports replace_all for renaming variables
  • Preserves indentation
• When to use: Prefer editing over writing new files; ideal for targeted changes
• Requirements: Must read file first before editing

Write

• Purpose: Create new files or overwrite existing ones
• Capabilities: Writes complete file content
• When to use: Only for creating genuinely new files; avoid for existing files (use Edit instead)
• Requirements: Must read file first if it exists

NotebookEdit

• Purpose: Edit Jupyter notebook (.ipynb) cells
• Capabilities:
  • Replace, insert, or delete cells
  • Supports code and markdown cells
• When to use: Working with Jupyter notebooks in the project

Search & Discovery

Glob

• Purpose: Fast file pattern matching
• Capabilities:
  • Supports glob patterns like **/*.js, src/**/*.ts
  • Returns files sorted by modification time
• When to use: Finding files by name patterns; use for specific needle queries
• Example: **/*.py to find all Python files

Grep

• Purpose: Powerful content search (built on ripgrep)
• Capabilities:
  • Full regex support
  • Filter by glob or file type
  • Output modes: content, files_with_matches, count
  • Context lines (-A, -B, -C)
  • Multiline matching support
• When to use: Searching for code patterns, function definitions, or specific strings
• Important: Use Task with Explore agent for open-ended exploratory searches

Execution & System

Bash

• Purpose: Execute bash commands
• Capabilities:
  • Git operations
  • Package management (npm, pip, etc.)
  • Build commands
  • Testing
  • System operations
• When to use: Terminal operations, git, npm, docker, but NOT for file reading/searching (use specialized tools)
• Best practices:
  • Use && for sequential dependent commands
  • Quote paths with spaces
  • Avoid cd; use absolute paths instead
  • Never skip git hooks unless explicitly requested

TaskOutput

• Purpose: Retrieve output from running/completed background tasks
• When to use: Check status of background shells or agents

TaskStop

• Purpose: Stop running background tasks
• When to use: Terminate long-running processes

Planning & Task Management

TodoWrite

• Purpose: Create and manage structured task lists
• Capabilities:
  • Track tasks with states: pending, in_progress, completed
  • Organize complex multi-step work
• When to use:
  • Complex tasks with 3+ steps
  • Multi-file changes
  • User provides multiple tasks
  • Before starting work on each task
• Best practice: Mark todos completed immediately after finishing; maintain exactly ONE in_progress task at a time

EnterPlanMode / ExitPlanMode

• Purpose: Enter planning mode for implementation design
• When to use:
  • New feature implementation
  • Multiple valid approaches exist
  • Architectural decisions needed
  • Multi-file changes
  • Unclear requirements
• When NOT to use: Simple one-line fixes, trivial tasks, pure research

AskUserQuestion

• Purpose: Ask user questions during execution
• Capabilities:
  • Multiple choice questions (2-4 options)
  • Multi-select support
  • Collects user preferences and clarifications
• When to use: Need clarification on requirements, implementation choices, or ambiguous instructions

Web & Information

WebFetch

• Purpose: Fetch and analyze web content
• Capabilities:
  • Converts HTML to markdown
  • 15-minute cache
• Limitations: WILL FAIL for authenticated/private URLs
• When to use: Public documentation, articles, reference materials
• Note: For GitHub URLs, prefer gh CLI via Bash

WebSearch

• Purpose: Search the web for current information
• Capabilities:
  • Access to up-to-date information beyond knowledge cutoff
  • Domain filtering (allowed/blocked)
• Requirements: MUST include "Sources:" section with markdown links in response
• When to use: Current events, recent documentation, external references

ToolSearch

• Purpose: Load deferred MCP tools before use
• Capabilities:
  • Keyword search mode (e.g., "slack", "notebook")
  • Direct selection mode (e.g., "select:NotebookEdit")
  • Required keyword mode (e.g., "+linear create issue")
• When to use: MANDATORY before calling any deferred/MCP tool
• Important: This is a BLOCKING requirement - must load tools before calling them

---

Specialized Agents (via Task Tool)

The Task tool launches specialized agents for complex work. Each agent type has specific capabilities:

Bash Agent

• Specialty: Command execution
• Tools: Bash only
• When to use: Git operations, complex command sequences

general-purpose Agent

• Specialty: Complex research and multi-step tasks
• Tools: All tools
• When to use: Complex questions, keyword searches requiring multiple attempts

Explore Agent

• Specialty: Fast codebase exploration
• Tools: Read-only tools (Glob, Grep, Read, etc.)
• Thoroughness levels: quick, medium, very thorough
• When to use:
  • "Where are errors handled?"
  • "How do API endpoints work?"
  • "What is the codebase structure?"
• Critical: Use this instead of manual Glob/Grep for exploratory searches

Plan Agent

• Specialty: Implementation planning and architecture design
• Tools: Read-only tools
• When to use: Design implementation strategy, identify critical files, consider architectural trade-offs

feature-dev Agents

• code-architect: Design feature architectures
• code-explorer: Analyze existing features and patterns
• code-reviewer: Review code for bugs and quality issues

---

Available Skills (via Skill Tool)

Skills are invoked when users reference slash commands (e.g., /commit).

feature-dev:feature-dev

• Purpose: Guided feature development with architecture focus
• When to use: Building new features from scratch

frontend-design:frontend-design

• Purpose: Create production-grade frontend interfaces
• When to use: Building web components, pages, or applications
• Goal: Avoid generic AI aesthetics; create polished, distinctive designs

Figma Integration Skills

• figma:code-connect-components: Map Figma designs to code components
• figma:create-design-system-rules: Generate custom design system rules
• figma:implement-design: Translate Figma designs to production code
• Requirement: Figma MCP server connection

---

MCP Servers (Deferred Tools)

These tools must be loaded via ToolSearch before use.

GitHub MCP Server

Prefix: mcp__github__*

Available Operations:

• Repository: create, fork, search repositories
• Files: get contents, create/update files, push files
• Branches: create, list commits
• Issues: create, list, update, get, add comments, search
• Pull Requests: create, list, get, merge, review, get files/status/comments
• Search: code, issues, users

When to use: GitHub operations beyond what gh CLI provides

Filesystem MCP Server

Prefix: mcp__filesystem__*

Available Operations:

• Read: read_file, read_text_file, read_media_file, read_multiple_files
• Write: write_file, edit_file
• Directory: create, list, tree, list_with_sizes
• Operations: move, search files, get file info
• Management: list_allowed_directories

When to use: Complex filesystem operations; prefer built-in Read/Write/Edit for simple operations

MS365 MCP Server

Prefix: mcp__ms365__*

Available Operations:

• Authentication: login, logout, verify, list/select/remove accounts
• Teams: chat operations, channel messages, team management
• OneDrive: file operations, Excel operations (worksheets, charts, ranges)
• Outlook: mail operations, calendar events, contacts
• SharePoint: site operations, lists, items
• Planner: tasks and plans
• OneNote: notebooks, sections, pages
• Todo: task lists and tasks

When to use: Integration with Microsoft 365 services

---

Project-Specific Context: Apoklisis

Environment

• Repository: Git repository on main branch
• Platform: Windows (win32)
• IDE: VSCode with native Claude Code extension
• Recent Activity:
  • Backend fixes: passlib/bcrypt integration (pinned bcrypt to 4.1.2)
  • DateTime timezone issue fixes
  • Clean working tree (as of last snapshot)

Recent Commits

a3efe68 Committing before moving to local disk
a6fc86c Pin bcrypt version to 4.1.2 for passlib compatibility
fa632da Fix backend: add passlib/bcrypt, fix datetime timezone issues

Technology Stack (Inferred)

• Backend: Python (passlib, bcrypt for authentication)
• Key Considerations:
  • Password hashing with passlib
  • Timezone handling for datetime operations
  • Dependency version compatibility (bcrypt pinned)

File Reference Format

When referencing code in VSCode, use markdown links:

• Files: [filename.ts](src/filename.ts)
• Specific lines: [filename.ts:42](src/filename.ts#L42)
• Line ranges: [filename.ts:42-51](src/filename.ts#L42-L51)
• Folders: [src/utils/](src/utils/)

---

Development Guidelines

General Workflow

1. Read First: Always read files before editing
2. Plan Complex Tasks: Use TodoWrite for multi-step work
3. Use Specialized Tools: Prefer dedicated tools over bash commands for file operations
4. Explore Efficiently: Use Task with Explore agent for codebase exploration
5. Parallel Execution: Make independent tool calls in parallel when possible

Code Modification Principles

• Avoid Over-Engineering: Only make requested changes
• No Premature Abstraction: Don't create utilities for one-time operations
• Security First: Watch for command injection, XSS, SQL injection, OWASP Top 10
• Simplicity: Keep solutions focused and minimal
• No Unnecessary Additions: Don't add error handling for impossible scenarios

Git Best Practices

• Never update git config
• Never run destructive commands (push --force, reset --hard) without explicit request
• Never skip hooks (--no-verify, --no-gpg-sign)
• Always create NEW commits (don't amend unless requested)
• Prefer staging specific files over git add -A or git add .
• Only commit when explicitly requested
• Include co-author tag: Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Pull Request Workflow

1. Run git status, git diff, check branch state
2. Analyze ALL commits from branch divergence (not just latest)
3. Keep PR title under 70 characters
4. Use HEREDOC for PR body with format:

   ## Summary
   <1-3 bullet points>
   
   ## Test plan
   [Checklist of testing TODOs]
   
   🤖 Generated with [Claude Code](https://claude.com/claude-code)
   

Communication Style

• Concise: Short, focused responses for CLI display
• No Emojis: Unless explicitly requested
• No Time Estimates: Never predict how long tasks will take
• Objective: Technical accuracy over validation
• Direct: Use markdown formatting, output text directly (not via echo/bash)

When to Ask for Help

• User Questions: Use AskUserQuestion for clarifications
• Planning: Use EnterPlanMode for complex implementation decisions
• Feedback: Direct users to https://github.com/anthropics/claude-code/issues

---

Quick Reference: Tool Selection Decision Tree

Need to find files by name pattern?
  → Use Glob

Need to search for code content?
  → Specific query? → Use Grep
  → Exploratory search? → Use Task (Explore agent)

Need to read a file?
  → Use Read (not cat)

Need to modify existing file?
  → Use Edit (not sed/awk)

Need to create new file?
  → Use Write (not echo/heredoc)

Need to execute command/git/npm?
  → Use Bash

Need to plan complex implementation?
  → Use EnterPlanMode

Need to track multi-step task?
  → Use TodoWrite

Need GitHub/MS365/filesystem MCP operations?
  → First: ToolSearch to load tool
  → Then: Call the loaded MCP tool

Need to ask user a question?
  → Use AskUserQuestion

---

Notes for Future Sessions

• Context Persistence: Conversations have unlimited context through automatic summarization
• Tool Results: May include <system-reminder> tags with useful information
• Model: Powered by Claude Sonnet 4.5 (claude-sonnet-4-5-20250929)
• Knowledge Cutoff: January 2025
• Current Date: Always use 2026 in current date calculations

---

Security Policy

Defensive Security Only

• Assist with security analysis, detection rules, vulnerability explanations
• Create defensive tools and security documentation
• Refuse: Code for malicious use, credential harvesting, bulk SSH key/cookie/wallet crawling

---

This reference guide should be consulted at the start of each session to ensure effective use of all available tools and maintain consistency with project conventions.