Rename project from HackToFuture 4.0 to Fun-Tastic

.agents/skills/deep-research/README.md

@@ -0,0 +1,119 @@
+# Deep Research Skill for Claude Code
+
+Enterprise-grade research engine for Claude Code. Produces citation-backed reports with source credibility scoring, multi-provider search, and automated validation.
+
+## Installation
+
+```bash
+# Clone into Claude Code skills directory
+git clone https://github.com/199-biotechnologies/claude-deep-research-skill.git ~/.claude/skills/deep-research
+```
+
+No additional dependencies required for basic usage.
+
+### Optional: search-cli (multi-provider search)
+
+For aggregated search across Brave, Serper, Exa, Jina, and Firecrawl:
+
+```bash
+brew tap 199-biotechnologies/tap && brew install search-cli
+search config set keys.brave YOUR_KEY  # configure at least one provider
+```
+
+## Usage
+
+```
+deep research on the current state of quantum computing
+```
+
+```
+deep research in ultradeep mode: compare PostgreSQL vs Supabase for our stack
+```
+
+## Research Modes
+
+| Mode | Phases | Duration | Best For |
+|------|--------|----------|----------|
+| Quick | 3 | 2-5 min | Initial exploration |
+| Standard | 6 | 5-10 min | Most research questions |
+| Deep | 8 | 10-20 min | Complex topics, critical decisions |
+| UltraDeep | 8+ | 20-45 min | Comprehensive reports, maximum rigor |
+
+## Pipeline
+
+Scope → Plan → **Retrieve** (parallel search + agents) → Triangulate → Outline Refinement → Synthesize → Critique (with loop-back) → Refine → Package
+
+Key features:
+- **Step 0**: Retrieves current date before searches (prevents stale training-data year assumptions)
+- **Parallel retrieval**: 5-10 concurrent searches + 2-3 focused sub-agents returning structured evidence objects
+- **First Finish Search**: Adaptive quality thresholds by mode
+- **Critique loop-back**: Phase 6 can return to Phase 3 with delta-queries if critical gaps found
+- **Multi-persona red teaming**: Skeptical Practitioner, Adversarial Reviewer, Implementation Engineer (Deep/UltraDeep)
+- **Disk-persisted citations**: `sources.json` survives context compaction and continuation agents
+
+## Output
+
+Reports saved to `~/Documents/[Topic]_Research_[Date]/`:
+- Markdown (primary source of truth)
+- HTML (McKinsey-style, auto-opened in browser)
+- PDF (professional print via WeasyPrint)
+
+Reports >18K words auto-continue via recursive agent spawning with context preservation.
+
+## Quality Standards
+
+- 10+ sources, 3+ per major claim
+- Executive summary 200-400 words
+- Findings 600-2,000 words each, prose-first (>=80%)
+- Full bibliography with URLs, no placeholders
+- Automated validation: `validate_report.py` (9 checks) + `verify_citations.py` (DOI/URL/hallucination detection)
+- Validation loop: validate → fix → retry (max 3 cycles)
+
+## Search Tools
+
+| Tool | Priority | Setup |
+|------|----------|-------|
+| search-cli | **Primary** — all searches go here first | `brew install search-cli` + API keys |
+| WebSearch | Fallback — if search-cli fails or rate-limited | None (built-in) |
+| Exa MCP | Optional — semantic/neural search alongside search-cli | MCP config |
+
+## Architecture
+
+```
+deep-research/
+├── SKILL.md                          # Skill entry point (lean, ~100 lines)
+├── reference/
+│   ├── methodology.md                # 8-phase pipeline details
+│   ├── report-assembly.md            # Progressive generation strategy
+│   ├── quality-gates.md              # Validation standards
+│   ├── html-generation.md            # McKinsey HTML conversion
+│   ├── continuation.md               # Auto-continuation protocol
+│   └── weasyprint_guidelines.md      # PDF generation
+├── templates/
+│   ├── report_template.md            # Report structure template
+│   └── mckinsey_report_template.html # HTML report template
+├── scripts/
+│   ├── validate_report.py            # 9-check structure validator
+│   ├── verify_citations.py           # DOI/URL/hallucination checker
+│   ├── source_evaluator.py           # Source credibility scoring
+│   ├── citation_manager.py           # Citation tracking
+│   ├── md_to_html.py                 # Markdown to HTML converter
+│   ├── verify_html.py                # HTML verification
+│   └── research_engine.py            # Core orchestration engine
+└── tests/
+    └── fixtures/                     # Test report fixtures
+```
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 2.3.1 | 2026-03-19 | Template/validator harmonization, structured evidence, critique loop-back, multi-persona red teaming |
+| 2.3 | 2026-03-19 | Contract harmonization, search-cli integration, dynamic year detection, disk-persisted citations, validation loops |
+| 2.2 | 2025-11-05 | Auto-continuation system for unlimited length |
+| 2.1 | 2025-11-05 | Progressive file assembly |
+| 1.0 | 2025-11-04 | Initial release |
+
+## License
+
+MIT - modify as needed for your workflow.

.agents/skills/deep-research/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: deep-research
+description: Use when the user needs multi-source research with citation tracking, evidence persistence, and structured report generation. Triggers on "deep research", "comprehensive analysis", "research report", "compare X vs Y", "analyze trends", or "state of the art". Not for simple lookups, debugging, or questions answerable with 1-2 searches.
+---
+
+# Deep Research
+
+## Core Purpose
+
+Deliver citation-tracked research reports through a structured pipeline with evidence persistence, source identity management, claim-level verification, and progressive context management.
+
+**Autonomy Principle:** Operate independently. Infer assumptions from context. Only stop for critical errors or incomprehensible queries. Surface high-materiality assumptions explicitly in the Introduction and Methodology rather than silently defaulting.
+
+---
+
+## Decision Tree
+
+```
+Request Analysis
++-- Simple lookup? --> STOP: Use WebSearch
++-- Debugging? --> STOP: Use standard tools
++-- Complex analysis needed? --> CONTINUE
+
+Mode Selection
++-- Initial exploration --> quick (3 phases, 2-5 min)
++-- Standard research --> standard (6 phases, 5-10 min) [DEFAULT]
++-- Critical decision --> deep (8 phases, 10-20 min)
++-- Comprehensive review --> ultradeep (8+ phases, 20-45 min)
+```
+
+**Default assumptions:** Technical query = technical audience. Comparison = balanced perspective. Trend = recent 1-2 years.
+
+---
+
+## Workflow Overview
+
+| Phase | Name | Quick | Std | Deep | Ultra |
+|-------|------|-------|-----|------|-------|
+| 1 | SCOPE | Y | Y | Y | Y |
+| 2 | PLAN | - | Y | Y | Y |
+| 3 | RETRIEVE | Y | Y | Y | Y |
+| 4 | TRIANGULATE | - | Y | Y | Y |
+| 4.5 | OUTLINE REFINEMENT | - | Y | Y | Y |
+| 5 | SYNTHESIZE | - | Y | Y | Y |
+| 6 | CRITIQUE | - | - | Y | Y |
+| 7 | REFINE | - | - | Y | Y |
+| 8 | PACKAGE | Y | Y | Y | Y |
+
+**Note:** Phases 3-5 operate as an evidence loop per section (retrieve → evidence store → refine outline → draft → verify claims → delta-retrieve if needed), not as strict sequential gates.
+
+---
+
+## Execution
+
+**On invocation, load relevant reference files:**
+
+1. **Phase 1-7:** Load [methodology.md](./reference/methodology.md) for detailed phase instructions
+2. **Phase 8 (Report):** Load [report-assembly.md](./reference/report-assembly.md) for progressive generation
+3. **HTML/PDF output:** Load [html-generation.md](./reference/html-generation.md)
+4. **Quality checks:** Load [quality-gates.md](./reference/quality-gates.md)
+5. **Long reports (>18K words):** Load [continuation.md](./reference/continuation.md)
+
+**Templates:**
+- Report structure: [report_template.md](./templates/report_template.md)
+- HTML styling: [mckinsey_report_template.html](./templates/mckinsey_report_template.html)
+
+**Scripts:**
+- `python scripts/validate_report.py --report [path]`
+- `python scripts/verify_citations.py --report [path]`
+- `python scripts/md_to_html.py [markdown_path]`
+
+---
+
+## Output Contract
+
+**Required sections:**
+- Executive Summary (200-400 words)
+- Introduction (scope, methodology, assumptions)
+- Main Analysis (4-8 findings, 600-2,000 words each, cited)
+- Synthesis & Insights (patterns, implications)
+- Limitations & Caveats
+- Recommendations
+- Bibliography (COMPLETE - every citation, no placeholders)
+- Methodology Appendix
+
+**Output files (all to `~/Documents/[Topic]_Research_[YYYYMMDD]/`):**
+- Markdown (primary source of truth)
+- `sources.jsonl` — stable source registry with canonical IDs
+- `evidence.jsonl` — append-only evidence store with quotes and locators
+- `claims.jsonl` — atomic claim ledger with support status
+- `run_manifest.json` — query, mode, assumptions, provider config
+- HTML (McKinsey style, auto-opened)
+- PDF (professional print, auto-opened)
+
+**Quality standards:**
+- 10+ sources, 3+ per major claim (cluster-independent, not just count)
+- All factual claims cited immediately [N] with evidence backing in `evidence.jsonl`
+- Claim-support verification mandatory: no unsupported factual claims pass delivery
+- No placeholders, no fabricated citations
+- Prose-first (>=80%), bullets sparingly
+
+---
+
+## When to Use / NOT Use
+
+**Use:** Comprehensive analysis, technology comparisons, state-of-the-art reviews, multi-perspective investigation, market analysis.
+
+**Do NOT use:** Simple lookups, debugging, 1-2 search answers, quick time-sensitive queries.

.agents/skills/deep-research/reference/continuation.md

@@ -0,0 +1,167 @@
+# Auto-Continuation Protocol
+
+## When to Use
+
+Trigger auto-continuation when report exceeds 18,000 words in single run.
+
+---
+
+## Strategy Overview
+
+1. Generate sections 1-10 (stay under 18K words)
+2. Save continuation state file with context preservation
+3. Spawn continuation agent via Task tool
+4. Continuation agent: Reads state -> Generates next batch -> Spawns next if needed
+5. Chain continues recursively until complete
+
+---
+
+## Continuation State File
+
+**Location:** `~/.claude/research_output/continuation_state_[report_id].json`
+
+```json
+{
+  "version": "3.0.0",
+  "report_id": "[unique_id]",
+  "file_path": "[absolute_path_to_report.md]",
+  "mode": "[quick|standard|deep|ultradeep]",
+
+  "progress": {
+    "sections_completed": ["list of section IDs"],
+    "total_planned_sections": 15,
+    "word_count_so_far": 12000,
+    "continuation_count": 1
+  },
+
+  "artifacts": {
+    "sources_path": "[folder]/sources.jsonl",
+    "evidence_path": "[folder]/evidence.jsonl",
+    "claims_path": "[folder]/claims.jsonl",
+    "run_manifest_path": "[folder]/run_manifest.json"
+  },
+
+  "research_context": {
+    "research_question": "[original question]",
+    "key_themes": ["theme1", "theme2"],
+    "main_findings_summary": [
+      "Finding 1: [100-word summary]",
+      "Finding 2: [100-word summary]"
+    ],
+    "narrative_arc": "middle"
+  },
+
+  "quality_metrics": {
+    "avg_words_per_finding": 1500,
+    "citation_density": 5.2,
+    "prose_vs_bullets_ratio": "85% prose",
+    "writing_style": "technical-precise-data-driven"
+  },
+
+  "next_sections": [
+    {"id": 11, "type": "finding", "title": "Finding X", "target_words": 1500},
+    {"id": 12, "type": "synthesis", "title": "Synthesis", "target_words": 1000}
+  ]
+}
+```
+
+---
+
+## Spawning Continuation Agent
+
+Use Task tool:
+
+```
+Task(
+  subagent_type="general-purpose",
+  description="Continue deep-research report generation",
+  prompt="""
+CONTINUATION TASK: Continue existing deep-research report.
+
+CRITICAL INSTRUCTIONS:
+1. Read continuation state: ~/.claude/research_output/continuation_state_[report_id].json
+2. Read existing report: [file_path from state]
+3. Read LAST 3 completed sections for flow/style
+4. Load research context: themes, narrative arc, writing style
+5. Load source registry from state.artifacts.sources_path — use stable source_ids, assign display numbers via citation_manager.py
+6. Maintain quality metrics (avg words, citation density, prose ratio)
+
+YOUR TASK:
+Generate next batch (stay under 18,000 words):
+[List next_sections from state]
+
+Use Write/Edit to append to: [file_path]
+
+QUALITY GATES:
+- Words per section: Within +/-20% of avg_words_per_finding
+- Citation density: Match +/-0.5 per 1K words
+- Prose ratio: Maintain >=80%
+- Theme alignment: Section ties to key_themes
+
+After generating:
+- If more sections remain: Update state, spawn next agent
+- If final sections: Generate bibliography, verify report, cleanup state
+"""
+)
+```
+
+---
+
+## Continuation Agent Quality Protocol
+
+### Context Loading (CRITICAL)
+
+1. Read continuation_state.json -> Load ALL context
+2. Read existing report file -> Review last 3 sections
+3. Extract patterns:
+   - Sentence structure complexity
+   - Technical terminology used
+   - Citation placement patterns
+   - Paragraph transition style
+
+### Pre-Generation Checklist
+
+- [ ] Loaded research context (themes, question, narrative arc)
+- [ ] Reviewed previous sections for flow
+- [ ] Loaded source registry from artifacts (stable source_ids, not citation numbers)
+- [ ] Loaded quality targets (words, density, style)
+- [ ] Understand narrative position (beginning/middle/end)
+
+### Per-Section Generation
+
+1. Generate section content
+2. Quality checks:
+   - Word count within +/-20%
+   - Citation density matches
+   - Prose ratio >=80%
+   - Theme connection verified
+   - Style consistent
+3. If ANY fails: Regenerate
+4. If passes: Write to file, update state
+
+### Handoff Decision
+
+Calculate: Current words + remaining sections x avg_words_per_section
+- If total < 18K: Generate all + finish
+- If total > 18K: Generate partial, update state, spawn next agent
+
+### Final Agent Responsibilities
+
+- Generate final content sections
+- Generate COMPLETE bibliography from state.citations.bibliography_entries
+- Read entire assembled report
+- Run validation: `python scripts/validate_report.py --report [path]`
+- Delete continuation_state.json (cleanup)
+- Report complete to user
+
+---
+
+## User Communication
+
+After spawning continuation:
+```
+Report Generation: Part 1 Complete (N sections, X words)
+Auto-continuing via spawned agent...
+   Next batch: [section list]
+   Progress: [X%] complete
+```