saline-intrusion-coastal-farming-agent-skill

saline-intrusion-coastal-farming

Coastal Saline-Intrusion Risk Forecasting & Soil-Washing Planning for Farms

A professional-grade, open-source Claude Code harness for Coastal Agro-Hydrology & Salinity Management. It gathers real-time authoritative data, applies recognized domain methods (Maas-Hoffman crop salt-tolerance model, leaching requirement formula, soil salinity classification), integrates academic research via a self-updating knowledge base, and delivers evidence-backed, risk-disclosed outputs in Vietnamese or English.

v2.0.0 adds a modular skill-registry architecture (saline_skill/): a typed tool framework, lifecycle hooks, a chain-of-thought router, type-safe configuration, and modular directories (scripts/, references/, assets/, config/). See SKILL.md for the registry specification.

Features

• 🌊 Saline-Intrusion Risk Forecasting — 5-factor intrusion risk model (tidal amplitude, rainfall deficit, groundwater salinity, coastal distance, sea-level rise)
• 🌾 Crop Salt-Tolerance Modeling — Maas-Hoffman threshold-slope model for 18 crops with weighted root-zone ECe
• 🧂 Soil Classification — Saline / Sodic / Saline-Sodic using ECe (4 dS/m), ESP (15%), and pH thresholds
• 💧 Leaching Requirement — LR = EC_iw / (5 × EC_e − EC_iw) with full reclamation plan (water volume, gypsum, drainage)
• 📅 Sowing Calendar Optimization — shift sowing off the peak-salinity window with cultivar substitution
• 📚 Self-Improving Knowledge Base — weekly crawl (ArXiv + Semantic Scholar + RSS) with SHA256 dedup + composite scoring
• 🧩 Modular Skill Registry — register / resolve / execute / validate skills with JSON I/O schemas
• 🪝 Lifecycle Hooks — pre_run, pre/post_skill, on_error, on_degradation, on_gate_fail, post_run (a failing hook never crashes the run)
• 🧭 Chain-of-Thought Router — adapts execution order to state (reuse, skip, level-4 short-circuit)
• ⚙️ Type-safe Config — env-first, YAML defaults, system-wide feature flags
• 🚪 10 Quality Gates — U1–U6 (universal) + G1–G4 (domain) with auto-fix and 2-retry max
• 📶 5-Level Graceful Degradation — Tier A→E fallback with explicit LIMITATION notices; tools never raise
• 🌐 Bilingual — automatic Vietnamese/English detection (gate U4)
• ✅ Production Testing — 5 E2E scenarios + 4 validators (315 checks) + 24 package unit tests

Repository layout

saline-intrusion-coastal-farming/
├── saline_skill/        # Modular agent harness (registry, schemas, hooks, router, tools, agents, harness)
│   ├── tools/           # Typed tools: web_search, maas_hoffman, leaching_requirement, intrusion_score, ...
│   └── agents/          # 5 domain sub-agents mirroring skills/sub-*.md
├── config/              # Type-safe config: settings.py, default.yaml, feature flags
├── scripts/             # Automation: run_harness.py, seed_knowledge_base.py, setup.py, validate_architecture.py
├── references/          # Domain knowledge + prompt base-templates (RAG grounding)
├── assets/              # JSON I/O schemas, tool registry schema, system diagram
├── skills/              # Markdown skill specs: main.md + 5 sub-skills
├── tools/               # Knowledge crawl pipeline + validators
├── tests/               # E2E scenarios + package unit tests
├── SKILL.md             # Skill-registry specification (registration/resolution/execution/validation)
├── SECOND-KNOWLEDGE-BRAIN.md  # Living knowledge base
└── PROJECT-detail.md    # Full technical specification

Installation

git clone <repo-url>
cd 162-saline-intrusion-coastal-farming
python -m venv .venv
source .venv/bin/activate        # .venv\Scripts\activate on Windows
pip install -r requirements.txt
pip install pytest pytest-cov    # dev

The harness is dependency-light: requests, feedparser, and python-dateutil are only used by the live-data tools and the knowledge pipeline; all tools degrade gracefully when those (or network) are unavailable. PyYAML is optional (enables config/default.yaml).

Usage

As a Claude Code Skill

/saline-intrusion-coastal-farming Analyze saline intrusion risk for rice paddy at Thanh Phu, Ben Tre, Vietnam

The harness executes 6 steps: requirements → evidence → core-analysis → knowledge → advisor → quality gate.

As a CLI / library

python scripts/run_harness.py \
  --query "Analyze saline intrusion risk for rice farm at An Vinh, Soc Trang" \
  --location "An Vinh, Soc Trang" --distance-km 2.5 --crop rice \
  --soil-ece 5.2 --soil-esp 8 --soil-ph 7.8 --irrigation-ec 1.2 \
  --tidal-amplitude 2.0 --gw-ec 3.0 --et0 4.5 --season-days 90 \
  --sowing-date 2026-05-01 --peak-start 2026-03-01 --peak-end 2026-04-30 \
  --json report.json

Programmatic:

from saline_skill.harness import Harness

out = Harness().run("Analyze saline intrusion for rice farm at Soc Trang", {
    "object": "Farm A", "location": "Soc Trang", "distance_to_coast_km": 2.5,
    "crops": [{"name": "rice"}],
    "data": {"soil": {"ece_dS_m": 5.2, "esp_pct": 8.0, "ph": 7.8},
             "geohydro": {"irrigation_ec_dS_m": 1.2, "tidal_amplitude_m": 2.0, "gw_ec_dS_m": 3.0},
             "climate": {"et0_mm_per_day": 4.5, "season_days": 90,
                         "current_sowing_date": "2026-05-01",
                         "peak_salinity_start": "2026-03-01", "peak_salinity_end": "2026-04-30"}},
})
print(out["verdict"]["category"], out["gate_results"])
print(out["report_markdown"])

Knowledge pipeline

python tools/knowledge_updater.py --dry-run              # fetch + score, no write
python tools/knowledge_updater.py --news-only            # RSS only
python tools/knowledge_updater.py --keywords "soil salinity" "rice salt tolerance"
python scripts/seed_knowledge_base.py                   # (re)seed the brain

Setup

python scripts/setup.py --no-install   # checks Python ≥3.11, seeds brain, offline smoke test

Architecture

User query  ─►  Harness (saline_skill/harness.py)
                 ├─► Config (config/settings.py — env + YAML, type-safe)
                 ├─► Chain-of-thought Router (saline_skill/router.py)
                 ├─► Skill Registry (saline_skill/registry.py) → 5 SkillSpecs
                 ├─► Tools (saline_skill/tools/* — JSON schemas + handlers, graceful fallback)
                 ├─► Hooks (saline_skill/hooks.py — lifecycle, never crash)
                 └─► Quality Gates (U1–U6 + G1–G4, auto-fix + 2 retries)

See SKILL.md for the full registry specification and assets/system-diagram.md for the Mermaid diagram.

Domain methods

Data sources

Quality gates

Testing

python -m pytest tests/test_saline_skill.py -q     # 24 package unit tests
python scripts/validate_architecture.py            # modular architecture validator
python tools/test_knowledge_updater.py             # 8 knowledge-updater unit tests
python tools/run_test_scenarios.py                # structural & content validator
python tools/validate_project.py                  # 191-check 8-File Contract + architecture validator

CI runs all of the above on Python 3.11 and 3.12 across ubuntu/windows/macos.

Roadmap

• Phase 0: Research & Architecture
• Phase 1: Core Sub-Skills (5)
• Phase 2: Main Harness + 10 Quality Gates + Graceful Degradation
• Phase 3: Knowledge Pipeline (crawl + dedup + scoring + brain)
• Phase 4: Testing & Validation
• Phase 5: Integration & Polish (open-source ready)
• Phase 6: Modular Skill-Registry Architecture (v2.0.0)

Status: PRODUCTION READY v2.0.0

Contributing

See CONTRIBUTING.md for development setup, code style, and pull request checklist.

License

MIT — see LICENSE.

Citation

@software{saline-intrusion-coastal-farming,
  title  = {saline-intrusion-coastal-farming: Coastal Saline-Intrusion Risk Forecasting & Soil-Washing Planning for Farms},
  author = {saline-intrusion-coastal-farming Contributors},
  year   = {2026},
  version= {2.0.0},
  url    = {https://github.com/saline-intrusion-coastal-farming}
}