scitex 2.13.0__py3-none-any.whl → 2.15.1__py3-none-any.whl

scitex/scholar/docs/to_claude/guidelines/project/IMPORTANT-general-multi-agent-coordination.md

@@ -1,311 +0,0 @@
-<!-- ---
-!-- Timestamp: 2025-05-26 10:25:00
-!-- Author: ywatanabe
-!-- File: /home/ywatanabe/proj/gPAC/docs/to_claude/guidelines/project/general-multi-agent-coordination.md
-!-- --- -->
-
-# General Multi-Agent Coordination Guidelines
-
-## 🎯 Core Philosophy
-
-Multiple AI agents can work together efficiently by following these principles:
-1. **Clear Boundaries**: Each agent owns specific modules/files
-2. **Asynchronous Communication**: No blocking waits between agents
-3. **Human-Readable State**: All coordination visible in plain text
-4. **Graceful Failures**: System continues even if agents crash
-
-## 📋 Quick Start Checklist
-
-```bash
-# 1. Set agent identity
-export CLAUDE_ID="<role>-CLAUDE-<uuid>-<timestamp>"
-
-# 2. Check bulletin board before starting
-cat ./project_management/AGENT_BULLETIN_BOARD.md
-
-# 3. Claim your work area
-echo "Claiming: <module> by $CLAUDE_ID" >> AGENT_BULLETIN_BOARD.md
-
-# 4. Work independently
-# ... do your work ...
-
-# 5. Update status regularly (every 5-10 min)
-# 6. Hand off when complete
-```
-
-## 🏗️ Standard Project Structure
-
-```
-project_root/
-├── project_management/
-│   ├── AGENT_BULLETIN_BOARD.md    # Central coordination
-│   ├── .locks/                     # Lightweight locks (optional)
-│   └── .events/                    # Event notifications (optional)
-├── src/                            # Source code
-├── tests/                          # Test files
-├── docs/                           # Documentation
-└── scripts/                        # Utility scripts
-```
-
-## 📝 Bulletin Board Format
-
-```markdown
-# Project Agent Bulletin Board
-
-## Active Agents
-| Agent ID | Role | Module | Status | Progress | Last Update |
-|----------|------|--------|--------|----------|-------------|
-| core-CLAUDE-abc123-20250526 | Core Dev | auth | 🔄 | 75% | 10:30 |
-| test-CLAUDE-def456-20250526 | Testing | auth-tests | ⏳ | 0% | 10:25 |
-
-## Work Claims
-| Module/File | Agent | Claimed At | ETA |
-|-------------|-------|------------|-----|
-| src/auth.py | core-CLAUDE-abc123 | 10:15 | 11:00 |
-
-## Recent Handoffs
-| From | To | Module | Status | Time |
-|------|-----|--------|--------|------|
-| core-CLAUDE-abc123 | test-CLAUDE-* | auth | ✅ READY | 10:45 |
-
-## Blocked Work
-| Agent | Blocked On | Reason | Since |
-|-------|------------|--------|-------|
-| pay-CLAUDE-xyz789 | auth module | Needs auth.login() | 10:20 |
-```
-
-## 🔄 Communication Protocol
-
-### 1. Status Indicators
-- 🔄 **IN_PROGRESS**: Actively working
-- ✅ **COMPLETE**: Finished, ready for next
-- ⏳ **WAITING**: Waiting for dependency
-- 🆘 **BLOCKED**: Need help
-- ❌ **FAILED**: Task failed
-
-### 2. Update Frequency
-- **Starting work**: Immediate claim
-- **Progress update**: Every 5-10 minutes
-- **Blocking issue**: Immediate
-- **Completion**: Immediate
-- **Checking board**: Based on status (1-5 min)
-
-### 3. Message Templates
-
-#### Claiming Work
-```markdown
-### CLAIM: <module_name>
-Agent: <CLAUDE_ID>
-Time: <timestamp>
-Files: <file_list>
-Dependencies: <none|list>
-ETA: <estimated_time>
-```
-
-#### Status Update
-```markdown
-### UPDATE: <module_name>
-Agent: <CLAUDE_ID>
-Status: 🔄 <percentage>%
-Current: <what_doing>
-Next: <what_next>
-Blockers: <none|list>
-```
-
-#### Handoff
-```markdown
-### HANDOFF: <module_name>
-From: <CLAUDE_ID>
-To: <role-CLAUDE-*|specific_id>
-Files: <modified_files>
-Tests: <pass|fail|pending>
-Notes: <important_info>
-```
-
-## 🚦 Coordination Strategies
-
-### Strategy 1: Module-Based (Recommended)
-```
-Agent 1: src/auth/* (authentication)
-Agent 2: src/api/* (API endpoints)
-Agent 3: tests/* (all testing)
-Agent 4: docs/* (documentation)
-```
-
-### Strategy 2: Layer-Based
-```
-Agent 1: Database layer
-Agent 2: Business logic
-Agent 3: API layer
-Agent 4: Frontend
-```
-
-### Strategy 3: Feature-Based
-```
-Agent 1: User management feature
-Agent 2: Payment feature
-Agent 3: Reporting feature
-Agent 4: Integration tests
-```
-
-## 🔐 Conflict Prevention
-
-### 1. File-Level Coordination
-```python
-# Before modifying a file, check if it's claimed
-def can_modify_file(filepath, bulletin_board):
-    claims = parse_bulletin_board(bulletin_board)
-    return filepath not in claims or claims[filepath]['agent'] == my_id
-```
-
-### 2. Merge Coordination
-```bash
-# Only one agent merges at a time
-if acquire_lock("merge.lock"); then
-    git merge feature/my-branch
-    release_lock("merge.lock")
-    update_bulletin("MERGED: feature/my-branch")
-fi
-```
-
-### 3. Dependency Management
-```markdown
-## Dependency Graph
-auth → api → frontend
-     ↘ payments ↗
-```
-
-## 🛠️ Tools and Helpers
-
-### 1. Simple Lock Manager (Bash)
-```bash
-#!/bin/bash
-# lock.sh - Simple file-based locking
-
-acquire_lock() {
-    local resource=$1
-    local lockfile=".locks/${resource}.lock"
-    
-    # Try to create lock (atomic operation)
-    if (set -C; echo "$CLAUDE_ID:$(date +%s)" > "$lockfile") 2>/dev/null; then
-        return 0  # Success
-    else
-        return 1  # Failed
-    fi
-}
-
-release_lock() {
-    local resource=$1
-    rm -f ".locks/${resource}.lock"
-}
-
-# Usage
-if acquire_lock "merge"; then
-    echo "Got lock, proceeding..."
-    # Do work
-    release_lock "merge"
-else
-    echo "Could not acquire lock"
-fi
-```
-
-### 2. Bulletin Board Updater (Python)
-```python
-import re
-from datetime import datetime
-
-def update_bulletin_board(agent_id, module, status, progress):
-    with open('AGENT_BULLETIN_BOARD.md', 'r') as f:
-        content = f.read()
-    
-    # Update or add agent status
-    timestamp = datetime.now().strftime("%H:%M")
-    new_row = f"| {agent_id} | {module} | {status} | {progress}% | {timestamp} |"
-    
-    # Update existing or append new
-    if agent_id in content:
-        # Update existing row
-        pattern = rf"\| {agent_id} \|.*\|"
-        content = re.sub(pattern, new_row, content)
-    else:
-        # Add new row (implementation depends on format)
-        pass
-    
-    with open('AGENT_BULLETIN_BOARD.md', 'w') as f:
-        f.write(content)
-```
-
-## 📊 Best Practices
-
-### DO:
-1. ✅ Update bulletin board regularly
-2. ✅ Use clear, descriptive agent IDs
-3. ✅ Document your changes in handoffs
-4. ✅ Check for conflicts before starting
-5. ✅ Clean up stale locks/claims
-6. ✅ Keep updates concise but informative
-
-### DON'T:
-1. ❌ Modify files claimed by others
-2. ❌ Hold locks longer than necessary
-3. ❌ Skip status updates
-4. ❌ Make assumptions about other agents' work
-5. ❌ Create complex dependencies
-6. ❌ Use blocking waits
-
-## 🚨 Emergency Procedures
-
-### 1. Deadlock Resolution
-```markdown
-If all agents blocked > 10 minutes:
-1. Check dependency graph
-2. Identify circular dependencies
-3. One agent backs out
-4. Document in bulletin board
-```
-
-### 2. Abandoned Work
-```markdown
-If no update > 30 minutes:
-1. Work becomes claimable
-2. New agent can take over
-3. Document takeover in board
-```
-
-### 3. Merge Conflicts
-```markdown
-1. Agent who created conflict resolves
-2. Other agents pause merging
-3. Post resolution to board
-4. Others can resume
-```
-
-## 📈 Scaling Guidelines
-
-### 2-5 Agents
-- Simple bulletin board
-- No locks needed
-- Check board every 5 min
-
-### 5-10 Agents  
-- Bulletin board + event files
-- Lightweight locks for merges
-- Check board every 2-3 min
-
-### 10+ Agents
-- Consider message queue
-- Dedicated coordinator role
-- Automated conflict detection
-
-## 🎯 Success Metrics
-
-1. **No file conflicts**: Zero parallel edits to same file
-2. **High throughput**: Agents working in parallel 80%+ time
-3. **Low latency**: Handoffs complete within 5 minutes
-4. **Clear history**: Can trace all changes through bulletin board
-
-## Your Understanding Check
-Did you understand the guideline? If yes, please say:
-`CLAUDE UNDERSTOOD: <THIS FILE PATH HERE>`
-
-<!-- EOF -->

scitex/scholar/docs/to_claude/guidelines/project/IMPORTANT-multi-agent-protocol.md

@@ -1,97 +0,0 @@
-<!-- ---
-!-- Timestamp: 2025-05-26 02:32:59
-!-- Author: ywatanabe
-!-- File: /ssh:ywatanabe@sp:/home/ywatanabe/.dotfiles/.claude/to_claude/guidelines/project/IMPORTANT-multi-agent-protocol.md
-!-- --- -->
-
-# Multi-Agent Communication Protocol
-## Core Principles
-1. Use `$CLAUDE_ID` for agent identification: `{role}-CLAUDE-{id}-{date}`
-2. Single coordination file: `PROJECT_ROOT/project_management/AGENT_BULLETIN_BOARD.md`
-3. Clear module ownership with small overlap to avoid conflicts
-4. File-based async communication
-
-## Bulletin Board Structure
-```markdown
-# Project Agent Bulletin Board
-## Agent Status
-| Agent ID | Module | Status | Progress | Last Update |
-|----------|--------|--------|----------|-------------|
-| core-CLAUDE-123-20250526 | auth | 🔄 | 75% | 14:30 |
-| test-CLAUDE-456-20250526 | auth-tests | ⏳ | 0% | waiting |
-
-## Current Work
-### 🔄 IN PROGRESS
-- auth module (core-CLAUDE-123)
-- database layer (db-CLAUDE-789)
-
-### ✅ COMPLETED 
-- user model (model-CLAUDE-101) → ready for integration
-
-### 🆘 BLOCKED
-- payment service → needs auth completion
-
-## Dependencies
-auth → auth-tests → integration-tests
-database → auth → payment
-```
-
-## Communication Protocol
-### Claiming Work
-1. Check bulletin board availability
-2. Add agent entry with timeline
-3. Update status to 🔄 IN PROGRESS
-
-### Progress Updates
-```markdown
-### Agent: core-CLAUDE-123-20250526
-Module: auth
-Status: 🔄 75%
-Last: 2025-05-26 14:30
-Completed: login, logout
-Next: password reset
-Blockers: none
-Ready for: auth-tests agent can start
-```
-
-### Completion Handoff
-```markdown
-### HANDOFF: auth module
-From: core-CLAUDE-123
-Status: ✅ COMPLETE
-Files: src/auth.py, tests/test_auth.py
-Interface: AuthService.login(user, pass) → token
-Dependencies: database layer required
-Ready for: test-CLAUDE-456 integration
-```
-
-## Work Areas
-```
-PROJECT_ROOT/
-├── project_management/
-│   └── AGENT_BULLETIN_BOARD.md
-```
-
-## Status Indicators
-- 🔄 In Progress
-- ✅ Complete  
-- ⏳ Waiting
-- 🆘 Blocked
-- ❌ Failed
-
-## Best Practices
-1. Update bulletin board every 1 chain of work
-2. Signal completion before switching modules
-3. Document interfaces for dependent agents
-4. Use clear file paths in handoffs
-5. Test integration points before handoff
-6. Keep one agent per module boundary
-
-## Conflict Resolution
-1. Check bulletin board for ownership conflicts
-2. Document blockers immediately
-3. Escalate integration issues to bulletin board
-4. Use dependency order for priority
-```
-
-<!-- EOF -->

scitex/scholar/docs/to_claude/guidelines/project/IMPORTANT-project-management-bulletin-board.md

@@ -1,48 +0,0 @@
-<!-- ---
-!-- Timestamp: 2025-05-31 18:09:11
-!-- Author: ywatanabe
-!-- File: /home/ywatanabe/.dotfiles/.claude/to_claude/guidelines/project/IMPORTANT-project-management-bulletin-board.md
-!-- --- -->
-
-# Bulletin Board - Agent Communication
-
-In this project, other agents may be working simultaneously. As an inter-agent communication tool, we adopt a bulletin board system using a markdown file (`./project_management/BULLETIN-BOARD.md`). This aims to coordinate better, by reducing conflicts, sharing knowledge, and think from various aspects.
-
-
-
-## Usage Rules
-
-1. Read before starting work
-2. Write when:
-   - Starting new task
-   - Completing task
-   - Finding important information
-   - Need coordination
-
-## Entry Format
-
-```
-## Agent: $CLAUDE_ID
-Role: [your role] (Required)
-Status: [working on / completed] (Optional)
-Task: [brief description] (Required)
-Notes: [key findings/issues/suggestions/ideas/concerns] (Optional)
-@mentions: [if targeting specific agent] (Optional)
-Timestamp: YYYY-MMDD-HH:mm (Required)
-```
-
-## Other communication channels
-You are also expected to use these project-level files in a collaborative manner with keep shared space clean and tidy.
-- `./project_management/progress.md`
-- `./project_management/bug-reports/bug-repoort-<title>.md`
-  - If solved, move bug-report entry to:
-    `./project_management/bug-reports/solved/bug-repoort-<title>.md`
-- `./project_management/feature-requests/feature-request-<title>.md`
-  - If solved, move bug-report entry to:
-    `./project_management/feature-requests/solved/feature-request-<title>.md`
-
-## Your Understanding Check
-Did you understand the guideline? If yes, please say:
-`CLAUDE UNDERSTOOD: <THIS FILE PATH HERE>`
-
-<!-- EOF -->

scitex/scholar/docs/to_claude/guidelines/project/IMPORTANT-project-management-markdown.md

@@ -1,156 +0,0 @@
-<!-- ---
-!-- Timestamp: 2025-05-30 17:10:32
-!-- Author: ywatanabe
-!-- File: /home/ywatanabe/.dotfiles/.claude/to_claude/guidelines/project/IMPORTANT-project-management-markdown.md
-!-- --- -->
-
-Project management is conducted under `./project_management` directory.
-
-## Core Files and Locations
-- Original plan: `./project_management/USER_PLAN.md` (DO NOT EDIT)
-- Updated plans: `./project_management/CLAUDE_PLAN.md` (Use this as a persistent memory)
-- Progress tracking (Markdown): `./project_management/progress-<title>-<timestamp>.md`
-- Progress tracking (Mermaid) : `./project_management/progress-<title>-<timestamp>.mmd`
-- Memory across sessions: `./project_management/next_steps-<timestamp>.md`
-
-## Progress Format
-
-``` markdown
-# Title
-| Type | Stat | Description   |
-|------|------|---------------|
-| 🚀   | [x]  | Project Title |
-
-## Goals, Milestones, and Tasks
-#### 🎯 Goal 1: Description
-| Type | Stat | Description        |
-|------|------|--------------------|
-| 🎯   | [ ]  | Goal description   |
-|      |      | 📌 Justication     |
-|------|------|--------------------|
-| 🏁   | [ ]  | Milestone details  |
-|      | [J]  | Justication        |
-|------|------|--------------------|
-| 📋   | [x]  | Completed task     |
-|      | [J]  | 📌 `/path/to/file` |
-
-## Key Symbols
-| Symbol | Meaning       | Status | Meaning |
-|--------|---------------|--------|---------|
-| 🎯     | Goal          | [ ]    | TODO    |
-| 🏁     | Milestone     | [x]    | DONE    |
-| 📋     | Task          |        |         |
-| 💡     | Suggestion    |        |         |
-| 📌     | Justification |        |         |
-```
-
-## Visual Progress Management using Mermaid Diagram
-- `./project_management/progress-<title>-<timestamp>.mmd`
-  - Mermaid diagram definition file reflecting `./project_management/progress-<title>-<timestamp>.md`
-  - Use tags as well
-  - Use TD layout
-  - Understand the hierarchy and summarize into core elements
-  - Summarize up to most-important 7 elements
-
-- `./project_management/progress-<title>-<timestamp>.svg`
-  - SVG file created from the mermaid file
-
-- `./project_management/progress-<title>-<timestamp>.gif`
-  - GIF image created from the SVG file
-
-#### Rendering Tool
-Use `.claude/bin/render_mermaid.sh /path/to/mermaid/file.mmd`
-
-#### Example
-``` mermaid
-graph TD
-    subgraph Legend
-        Z1[Todo]:::todo
-        Z2[In Progress]:::inProgress
-        Z3[Done]:::done
-        Z4[Directory]:::directory
-    end
-    subgraph Project Structure
-    subgraph PD[Project Description]
-        PJNAME[Project Name]:::done
-        PJGOALS[Goals]:::done
-    end
-    subgraph PDIR[Project Directory]
-        Root["\/workspace\/projects\/000-sample-project"]:::directory
-        Config[config/]:::directory
-        Data[data/]:::directory
-        Scripts[scripts/]:::directory
-        Results[results/]:::directory
-        Resources[resources/]:::directory
-        Env[.env/]:::directory
-        Git[.git/]:::directory
-        Requirements[requirements.txt/]:::directory
-        Log[Log.txt/]:::directory
-        PM[project_management.mmd]:::directory
-    end
-    end
-    subgraph Execution Flow
-    subgraph Step
-        D[Compile Context]:::done
-        E[Generate Elisp]:::inProgress
-        F[Execute Elisp]:::todo
-        G{Success?}:::todo
-    end
-    subgraph "Logging, Version Control, and State Update"
-        H[Log Success]:::todo
-        I[Log Error]:::todo
-        J{Milestone?}:::todo
-        K[Git Commit]:::todo
-        L[Log Only]:::todo
-        M{Goal Met?}:::todo
-        N[Update Project_States]:::todo
-    end
-    end
-    subgraph PMFLOW[Project Management Flow]
-        MS1[Milestone 1]:::done
-        MS2[Milestone 2]:::inProgress
-    subgraph Tasks M1
-        T1[task1]:::done
-        T2[task2]:::done
-    end
-    subgraph Tasks M2
-        T3[task1]:::done
-        T4[task2]:::todo
-    end
-    end
-    Start[Start]:::starttag --> PD
-    PD --> PDIR
-    PM --> PMFLOW
-    PMFLOW --> PM
-    PDIR --> D
-    D --> E --> F --> G
-    G -- Yes --> H
-    G -- No --> I
-    H --> J
-    J -- Yes --> K
-    J -- No --> L
-    K --> M
-    I --> L
-    L --> M
-    M -- No --> N
-    N --> Root
-    M -- Yes --> End[End]:::endtag
-    PJGOALS --> PMFLOW
-    MS1 --> T1
-    MS1 --> T2
-    MS2 --> T3
-    MS2 --> T4
-    classDef starttag fill:#cce5ff,stroke:#333,stroke-width:2px;
-    classDef done fill:#9f9,stroke:#333,stroke-width:2px;
-    classDef inProgress fill:#ff9,stroke:#333,stroke-width:2px;
-    classDef todo fill:#fff,stroke:#333,stroke-width:2px;
-    classDef directory fill:#efe,stroke:#333,stroke-width:1px;
-    classDef endtag fill:#fcc,stroke:#333,stroke-width:2px;
-    class Root,Config,Data,Scripts,Results,Resources directory;
-```
-
-## Your Understanding Check
-Did you understand the guideline? If yes, please say:
-`CLAUDE UNDERSTOOD: <THIS FILE PATH HERE>`
-
-<!-- EOF -->