flonat-research 0.1.0

package/hooks/resume-context-loader.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+# Skip on non-Mac environments (cloud, mobile)
+source "$(dirname "$0")/resolve-task-mgmt.sh" || exit 0
+# resume-context-loader.sh
+# SessionStart hook (resume) — surfaces current focus and latest session log
+# so Claude picks up where things left off.
+FOCUS_FILE="$TASK_MGMT/.context/current-focus.md"
+LOG_DIR="$TASK_MGMT/log"
+
+CONTEXT=""
+
+# Read current focus
+if [ -f "$FOCUS_FILE" ]; then
+  FOCUS=$(head -20 "$FOCUS_FILE")
+  CONTEXT="## Current Focus\n$FOCUS"
+fi
+
+# Load project planning state (if in a project with orchestration)
+CWD="$(pwd)"
+if [ "$CWD" != "$TASK_MGMT" ]; then
+  PROJECT_ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null || echo "$CWD")
+  if [ -f "$PROJECT_ROOT/.planning/state.md" ]; then
+    STATE=$(head -30 "$PROJECT_ROOT/.planning/state.md")
+    CONTEXT="$CONTEXT\n\n## Project Planning State\n$STATE"
+  fi
+fi
+
+# Find latest session log (not plans, not compact saves)
+if [ -d "$LOG_DIR" ]; then
+  LATEST_LOG=$(find "$LOG_DIR" -maxdepth 1 -name "*.md" -type f | sort -r | head -1)
+  if [ -n "$LATEST_LOG" ] && [ -f "$LATEST_LOG" ]; then
+    LOG_SUMMARY=$(head -30 "$LATEST_LOG")
+    CONTEXT="$CONTEXT\n\n## Latest Session Log ($(basename "$LATEST_LOG"))\n$LOG_SUMMARY"
+  fi
+fi
+
+if [ -z "$CONTEXT" ]; then
+  exit 0
+fi
+
+# Escape for JSON
+CONTEXT_ESCAPED=$(echo -e "$CONTEXT" | jq -Rs .)
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": $CONTEXT_ESCAPED
+  }
+}
+EOF
+
+exit 0

package/hooks/startup-context-loader.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Skip on non-Mac environments (cloud, mobile)
+source "$(dirname "$0")/resolve-task-mgmt.sh" || exit 0
+# startup-context-loader.sh
+# SessionStart hook (startup) — auto-detects and surfaces project documentation
+# on fresh sessions in any project, so Claude doesn't waste tokens searching.
+CWD="$(pwd)"
+CONTEXT=""
+MAX_LINES=30
+
+add_section() {
+  local title="$1"
+  local file="$2"
+  local lines="${3:-$MAX_LINES}"
+
+  if [ -f "$file" ]; then
+    local content
+    content=$(head -"$lines" "$file")
+    if [ -n "$content" ]; then
+      if [ -n "$CONTEXT" ]; then
+        CONTEXT="$CONTEXT\n\n"
+      fi
+      CONTEXT="${CONTEXT}## ${title}\n${content}"
+    fi
+  fi
+}
+
+# --- Current focus (Task Management context) ---
+add_section "Current Focus" "$TASK_MGMT/.context/current-focus.md" 25
+
+# --- Project index (Task Management context) ---
+add_section "Project Index" "$TASK_MGMT/.context/projects/_index.md" 40
+
+# --- Resolve project root (handles subdirectory CWDs) ---
+if [ "$CWD" != "$TASK_MGMT" ]; then
+  PROJECT_ROOT=$(git -C "$CWD" rev-parse --show-toplevel 2>/dev/null || echo "$CWD")
+fi
+
+# --- MEMORY.md (structured knowledge tables and [LEARN] corrections) ---
+if [ "$CWD" = "$TASK_MGMT" ]; then
+  add_section "MEMORY.md" "$TASK_MGMT/MEMORY.md" 30
+else
+  add_section "Project MEMORY" "$PROJECT_ROOT/MEMORY.md" 30
+fi
+
+# --- Project-specific docs (if not in Task Management itself) ---
+if [ "$CWD" != "$TASK_MGMT" ]; then
+
+  add_section "Project README" "$PROJECT_ROOT/README.md" 40
+
+  # Check for project-specific context files
+  add_section "Project Focus" "$PROJECT_ROOT/.context/current-focus.md" 25
+
+  # Check for project planning state
+  add_section "Project Planning State" "$PROJECT_ROOT/.planning/state.md" 30
+fi
+
+# --- Latest session log ---
+if [ -d "$TASK_MGMT/log" ]; then
+  LATEST_LOG=$(find "$TASK_MGMT/log" -maxdepth 1 -name "*.md" -type f | sort -r | head -1)
+  add_section "Latest Session Log ($(basename "$LATEST_LOG" 2>/dev/null))" "$LATEST_LOG" 30
+fi
+
+# --- Latest plan (if any) ---
+if [ -d "$TASK_MGMT/log/plans" ]; then
+  LATEST_PLAN=$(find "$TASK_MGMT/log/plans" -maxdepth 1 -name "*.md" -type f | sort -r | head -1)
+  add_section "Latest Plan ($(basename "$LATEST_PLAN" 2>/dev/null))" "$LATEST_PLAN" 25
+fi
+
+# --- Skill observations: weekly review check ---
+REVIEW_DATE_FILE="$HOME/.claude/skill-observations/last-review-date.txt"
+if [ -f "$REVIEW_DATE_FILE" ]; then
+  LAST_REVIEW=$(cat "$REVIEW_DATE_FILE" | tr -d '\n')
+  DAYS_SINCE=$(( ( $(date +%s) - $(date -j -f "%Y-%m-%d" "$LAST_REVIEW" +%s 2>/dev/null || echo 0) ) / 86400 ))
+  if [ "$DAYS_SINCE" -ge 7 ] 2>/dev/null; then
+    if [ -n "$CONTEXT" ]; then
+      CONTEXT="$CONTEXT\n\n"
+    fi
+    CONTEXT="${CONTEXT}## Skill Observations\nWeekly review overdue (last: ${LAST_REVIEW}, ${DAYS_SINCE} days ago). Consider running \`/skill-health\` to review."
+  fi
+fi
+
+if [ -z "$CONTEXT" ]; then
+  exit 0
+fi
+
+# Add a header
+CONTEXT="# Session Context (auto-loaded)\nRead these docs — do NOT re-search for this information.\n\n${CONTEXT}"
+
+# Escape for JSON
+CONTEXT_ESCAPED=$(echo -e "$CONTEXT" | jq -Rs .)
+
+cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": $CONTEXT_ESCAPED
+  }
+}
+EOF
+
+exit 0

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "flonat-research",
+  "version": "0.1.0",
+  "description": "Claude Code infrastructure for academic research — skills, agents, hooks, and rules for LaTeX, bibliography, proofreading, and project management workflows.",
+  "author": "Florian Burnat",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flonat/claude-research.git"
+  },
+  "homepage": "https://github.com/flonat/claude-research",
+  "keywords": [
+    "claude-code",
+    "academic",
+    "research",
+    "latex",
+    "bibliography",
+    "proofreading",
+    "phd",
+    "skills",
+    "agents",
+    "hooks"
+  ],
+  "bin": {
+    "claude-research-setup": "scripts/setup.sh"
+  },
+  "scripts": {
+    "postinstall": "echo '\\nRun: npx claude-research-setup\\nto create symlinks for skills, agents, hooks, and rules.\\n'",
+    "setup": "bash scripts/setup.sh"
+  },
+  "files": [
+    "skills/",
+    "hooks/",
+    ".claude/agents/",
+    ".claude/rules/",
+    ".claude/settings.json",
+    ".context/",
+    ".scripts/",
+    ".mcp-server-biblio/",
+    "packages/",
+    "docs/",
+    "scripts/setup.sh",
+    "CLAUDE.md",
+    "MEMORY.md",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/packages/cli-council/.github/workflows/claude-code-review.yml

@@ -0,0 +1,44 @@
+name: Claude Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review, reopened]
+    # Optional: Only run on specific file changes
+    # paths:
+    #   - "src/**/*.ts"
+    #   - "src/**/*.tsx"
+    #   - "src/**/*.js"
+    #   - "src/**/*.jsx"
+
+jobs:
+  claude-review:
+    # Optional: Filter by PR author
+    # if: |
+    #   github.event.pull_request.user.login == 'external-contributor' ||
+    #   github.event.pull_request.user.login == 'new-developer' ||
+    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
+
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code Review
+        id: claude-review
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
+          plugins: 'code-review@claude-code-plugins'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+

package/packages/cli-council/.github/workflows/claude.yml

@@ -0,0 +1,50 @@
+name: Claude Code
+
+on:
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+  issues:
+    types: [opened, assigned]
+  pull_request_review:
+    types: [submitted]
+
+jobs:
+  claude:
+    if: |
+      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
+      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
+      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+      issues: read
+      id-token: write
+      actions: read # Required for Claude to read CI results on PRs
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+
+          # This is an optional setting that allows Claude to read CI results on PRs
+          additional_permissions: |
+            actions: read
+
+          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
+          # prompt: 'Update the pull request description to include a summary of changes.'
+
+          # Optional: Add claude_args to customize behavior and configuration
+          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
+          # or https://code.claude.com/docs/en/cli-reference for available options
+          # claude_args: '--allowed-tools Bash(gh pr:*)'
+

package/packages/cli-council/README.md

@@ -0,0 +1,100 @@
+# cli-council
+
+Local multi-model council deliberation using CLI tools. Runs Gemini CLI, Codex CLI, and Claude Code in parallel to get diverse AI perspectives on any question — using your existing subscriptions, not per-token API costs.
+
+Part of [claude-research](https://github.com/user/claude-research) infrastructure.
+
+## How It Works
+
+Three-stage deliberation protocol (inspired by [Karpathy's llm-council](https://github.com/karpathy/llm-council)):
+
+1. **Stage 1: Independent Assessments** — Each CLI tool independently answers the same question in parallel
+2. **Stage 2: Anonymised Peer Review** — Each tool reviews all assessments (anonymised as "Assessment A/B/C") and ranks them
+3. **Stage 3: Chairman Synthesis** — One tool reads everything and produces a single synthesised answer
+
+## Prerequisites
+
+Install the CLI tools you want to use:
+
+| Backend | Install | Auth |
+|---------|---------|------|
+| **Gemini CLI** | `npm install -g @google/generative-ai-cli` | `gemini` (Google account) |
+| **Codex CLI** | `npm install -g @openai/codex-cli` | `codex login` (ChatGPT Plus) |
+| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | `claude` (Claude Pro) |
+
+Check availability:
+
+```bash
+python -m cli_council --check
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Simple question
+python -m cli_council "What are the tradeoffs between microservices and monoliths?"
+
+# With context file and markdown output
+python -m cli_council \
+    --prompt-file question.txt \
+    --context-file project-context.md \
+    --output-md council-report.md
+
+# Pipe from stdin
+echo "Review this research design for causal identification issues" | python -m cli_council
+
+# Select specific backends
+python -m cli_council --backends gemini,claude "Best approach for time-series forecasting?"
+
+# Change chairman
+python -m cli_council --chairman codex "Evaluate this argument..."
+```
+
+### Python API
+
+```python
+import asyncio
+from cli_council import CouncilRunner
+
+runner = CouncilRunner(
+    backends=["gemini", "codex", "claude"],
+    chairman="claude",
+)
+
+result = asyncio.run(runner.run(
+    "What are the key risks in this experimental design?",
+    system_context="We're studying the effect of AI assistance on decision quality...",
+))
+
+print(result.synthesis)
+for a in result.assessments:
+    print(f"{a.label} ({a.backend}): {a.text[:100]}...")
+print(f"Total time: {result.meta.total_ms}ms")
+```
+
+## Output
+
+Returns a `CouncilResult` with:
+
+- `synthesis` — Chairman's final synthesised answer
+- `assessments` — List of individual Stage 1 responses
+- `peer_reviews` — List of Stage 2 peer reviews with rankings
+- `meta` — Timing, backends used, errors
+
+## Relationship to llm-council
+
+| | cli-council | [llm-council](https://github.com/user/llm-council) |
+|---|---|---|
+| **Transport** | Local CLI subprocesses | OpenRouter API |
+| **Cost** | Subscription-included | Per-token |
+| **Output** | Free-form text | Structured JSON |
+| **Best for** | Ad-hoc reviews, research, quick opinions | Automated pipelines, structured reports |
+| **Models** | Whatever your CLIs support | Full OpenRouter catalogue |
+
+Both implement the same 3-stage protocol. Use cli-council for interactive work, llm-council for programmatic integration.
+
+## License
+
+MIT

package/packages/cli-council/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "cli-council"
+version = "0.1.0"
+description = "Local multi-model council deliberation via CLI tools (Gemini CLI, Codex CLI, Claude Code)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [
+    { name = "the user" },
+]
+keywords = ["llm", "council", "multi-model", "cli", "gemini", "codex", "claude"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/user/cli-council"
+Repository = "https://github.com/user/cli-council"
+Issues = "https://github.com/user/cli-council/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cli_council"]

package/packages/cli-council/src/cli_council/__init__.py

@@ -0,0 +1,19 @@
+"""cli-council: Local multi-model council deliberation via CLI tools."""
+
+from cli_council.checkpoint import CouncilCheckpointer
+from cli_council.council import CouncilRunner
+from cli_council.models import (
+    Assessment,
+    CouncilMeta,
+    CouncilResult,
+    PeerReview,
+)
+
+__all__ = [
+    "CouncilCheckpointer",
+    "CouncilRunner",
+    "Assessment",
+    "CouncilMeta",
+    "CouncilResult",
+    "PeerReview",
+]

package/packages/cli-council/src/cli_council/__main__.py

@@ -0,0 +1,185 @@
+"""CLI entry point: python -m cli_council."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import sys
+from pathlib import Path
+
+from cli_council.config import DEFAULT_CHAIRMAN, DEFAULT_COUNCIL_BACKENDS
+from cli_council.council import CouncilRunner
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="cli-council",
+        description="Run a multi-model council deliberation using local CLI tools.",
+    )
+    parser.add_argument(
+        "prompt",
+        nargs="?",
+        help="The question or task for the council. If omitted, reads from stdin.",
+    )
+    parser.add_argument(
+        "--prompt-file",
+        type=Path,
+        help="Read prompt from a file instead of argument/stdin.",
+    )
+    parser.add_argument(
+        "--context-file",
+        type=Path,
+        help="File with system context (project description, constraints, etc.).",
+    )
+    parser.add_argument(
+        "--backends",
+        type=str,
+        default=",".join(DEFAULT_COUNCIL_BACKENDS),
+        help=f"Comma-separated list of backends (default: {','.join(DEFAULT_COUNCIL_BACKENDS)}).",
+    )
+    parser.add_argument(
+        "--chairman",
+        type=str,
+        default=DEFAULT_CHAIRMAN,
+        help=f"Backend for Stage 3 synthesis (default: {DEFAULT_CHAIRMAN}).",
+    )
+    parser.add_argument(
+        "--timeout",
+        type=int,
+        default=120,
+        help="Timeout per backend call in seconds (default: 120).",
+    )
+    parser.add_argument(
+        "--output",
+        type=Path,
+        help="Write JSON result to file (default: stdout).",
+    )
+    parser.add_argument(
+        "--output-md",
+        type=Path,
+        help="Write markdown report to file.",
+    )
+    parser.add_argument(
+        "--cwd",
+        type=str,
+        help="Working directory for CLI tools (default: current directory).",
+    )
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Check which backends are available and exit.",
+    )
+    parser.add_argument(
+        "-v", "--verbose",
+        action="store_true",
+        help="Enable verbose logging.",
+    )
+    return parser.parse_args()
+
+
+def _format_markdown(result) -> str:
+    """Format a CouncilResult as a readable markdown report."""
+    lines = ["# Council Report\n"]
+
+    lines.append("## Synthesis\n")
+    lines.append(result.synthesis)
+    lines.append("")
+
+    lines.append("## Individual Assessments\n")
+    for a in result.assessments:
+        lines.append(f"### {a.label} ({a.backend}, {a.model})\n")
+        lines.append(a.text)
+        lines.append(f"\n*Elapsed: {a.elapsed_ms}ms*\n")
+
+    if result.peer_reviews:
+        lines.append("## Peer Reviews\n")
+        for r in result.peer_reviews:
+            lines.append(f"### Review by {r.backend} ({r.model})\n")
+            lines.append(r.review_text)
+            if r.parsed_ranking:
+                lines.append(f"\n**Ranking:** {' > '.join(r.parsed_ranking)}")
+            lines.append(f"\n*Elapsed: {r.elapsed_ms}ms*\n")
+
+    lines.append("## Metadata\n")
+    meta = result.meta
+    lines.append(f"- **Backends:** {', '.join(meta.backends_used)}")
+    lines.append(f"- **Chairman:** {meta.chairman_backend}")
+    lines.append(f"- **Timing:** Stage 1: {meta.stage1_ms}ms, Stage 2: {meta.stage2_ms}ms, Stage 3: {meta.stage3_ms}ms, Total: {meta.total_ms}ms")
+    if meta.errors:
+        lines.append(f"- **Errors:** {'; '.join(meta.errors)}")
+
+    return "\n".join(lines)
+
+
+def main() -> None:
+    args = _parse_args()
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+    # --check mode
+    if args.check:
+        backends = args.backends.split(",")
+        runner = CouncilRunner(backends=backends)
+        available = runner.available_backends()
+        print(f"Requested: {', '.join(backends)}")
+        print(f"Available: {', '.join(available) or 'none'}")
+        missing = set(backends) - set(available)
+        if missing:
+            print(f"Missing:   {', '.join(missing)}")
+            sys.exit(1)
+        print("All backends available.")
+        sys.exit(0)
+
+    # Resolve prompt
+    prompt: str | None = args.prompt
+    if args.prompt_file:
+        prompt = args.prompt_file.read_text().strip()
+    elif prompt is None:
+        if not sys.stdin.isatty():
+            prompt = sys.stdin.read().strip()
+        else:
+            print("Error: No prompt provided. Use positional arg, --prompt-file, or pipe via stdin.", file=sys.stderr)
+            sys.exit(1)
+
+    if not prompt:
+        print("Error: Empty prompt.", file=sys.stderr)
+        sys.exit(1)
+
+    # Resolve context
+    system_context = ""
+    if args.context_file:
+        system_context = args.context_file.read_text().strip()
+
+    # Run council
+    backends = [b.strip() for b in args.backends.split(",")]
+    runner = CouncilRunner(
+        backends=backends,
+        chairman=args.chairman,
+        timeout=args.timeout,
+        cwd=args.cwd,
+    )
+
+    result = asyncio.run(runner.run(prompt, system_context=system_context))
+
+    # Output JSON
+    result_json = result.model_dump()
+    if args.output:
+        args.output.write_text(json.dumps(result_json, indent=2) + "\n")
+        print(f"JSON result written to {args.output}", file=sys.stderr)
+    else:
+        print(json.dumps(result_json, indent=2))
+
+    # Output markdown
+    if args.output_md:
+        md = _format_markdown(result)
+        args.output_md.write_text(md + "\n")
+        print(f"Markdown report written to {args.output_md}", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

package/packages/cli-council/src/cli_council/backends/__init__.py

@@ -0,0 +1,8 @@
+"""CLI backend implementations."""
+
+from cli_council.backends.base import CLIBackend
+from cli_council.backends.claude import ClaudeBackend
+from cli_council.backends.codex import CodexBackend
+from cli_council.backends.gemini import GeminiBackend
+
+__all__ = ["CLIBackend", "ClaudeBackend", "CodexBackend", "GeminiBackend"]