adhd-friendly-home-design-agent-skill

adhd-friendly-home-design

ADHD-Friendly Home Space Optimization Advisor (Environmental Psychology)

A professional-grade Claude Code skill for ADHD environmental design and cognitive ergonomics. It gathers authoritative real-time data, applies recognized environmental-psychology methods, integrates academic research, and delivers evidence-backed, risk-disclosed, personalized home-design recommendations through a self-improving knowledge base.

Features

• Five-sub-skill harness with a strict 6-step protocol and a pre-flight language detection (Vietnamese / English).
• Ten quality gates (U1–U6 universal + G1–G4 domain) with auto-fix and a 2-retry limit; graceful degradation across 5 levels with explicit limitation banners.
• Safety-bounded recommendations against published reference ranges (melanopic illuminance, task lux, noise dBA, color temperature, clutter).
• Living knowledge base (SECOND-KNOWLEDGE-BRAIN.md) auto-updated by a crawl pipeline (Semantic Scholar + ArXiv + RSS) with SHA256 dedup and composite scoring.
• Production-grade toolchain: validators, unit tests, offline/dry-run modes, JSON export, env-var configuration, structured logging.
• Advanced architecture (v1.2.0): Event-driven hooks system, thread-safe state synchronization, typed configuration management, comprehensive documentation.

Installation

pip install -r requirements.txt          # runtime
pip install -r requirements-dev.txt      # + dev/CI tooling

Install the skill files to ~/.claude/skills/ or use them via the project CLAUDE.md.

Usage

Invoke the skill in Claude Code:

/adhd-friendly-home-design [your query]

Example queries:

• "Optimize the bedroom of a 12-year-old with inattentive ADHD for homework and sleep."
• "Tối ưu không gian phòng làm việc cho người trưởng thành ADHD, hay bị quá tải giác quan." (Vietnamese)

Knowledge pipeline

python tools/knowledge_updater.py                 # full crawl + append
python tools/knowledge_updater.py --dry-run        # plan only, no writes
python tools/knowledge_updater.py --news-only      # RSS only
python tools/knowledge_updater.py --offline        # no network (tests/CI)
python tools/knowledge_updater.py --export-json out.json

Validation and tests

python tools/validate_project.py          # 8-File Contract + production checks
python tools/test_knowledge_updater.py    # pipeline unit tests
python tools/run_test_scenarios.py        # structural & content validator

Setup scripts

python scripts/setup.py                    # Initialize development environment
python scripts/seed_knowledge.py           # Seed knowledge base with foundational content

Architecture

Harness flow:

requirements -> evidence -> core analysis -> knowledge -> synthesis -> quality gate

sub-gather-requirements -> sub-evidence-collector -> sub-core-analysis -> sub-knowledge-updater -> sub-advisor -> main harness quality-gate review.

v1.2.0 Architectural Enhancements

• Hooks System: Lifecycle hooks (pre-flight, post-analysis, quality gate, error), state synchronization with thread-safe operations, typed event bus with metrics
• Configuration: Type-safe SkillConfig and KnowledgeConfig with environment variable overrides, validation, and reference ranges
• Event System: Typed events with filtering, metrics collection, and history tracking
• Documentation: Comprehensive domain knowledge, evidence-based design patterns, and authoritative standards (WELL, CIE, WHO, ASHRAE)

See PROJECT-detail.md for the full architecture, skills/main.md for the execution protocol, and SKILL.md for the skill registry and triggering logic.

Quality gates

Universal gates U1–U6 plus domain gates G1–G4 (sensory + organizational measures, sleep/circadian environment, focus vs activity zones). See skills/main.md.

Verdict categories (exactly one)

Optimized Layout / Conditional (gradual changes) / High Sensory Load Risk / Inconclusive.

Data sources

• CHADD (Children and Adults with ADHD) — chadd.org
• ADDitude Magazine — additudemag.com
• ADHD Foundation (UK) — adhdfoundation.org.uk
• NIH NIMH — nimh.nih.gov
• WHO mental health / environmental noise — who.int
• WELL Building Standard — wellcertified.com
• CIE (melanopic/photobiological standards) — cie.co.at
• Journals: J. Attention Disorders, J. Environmental Psychology, Environment & Behavior, Building and Environment, Lighting Research and Technology.

Knowledge base

SECOND-KNOWLEDGE-BRAIN.md is auto-updated weekly (academic) and daily (news) via tools/knowledge_updater.py. See the cron/Task Scheduler schedule in CLAUDE.md.

Roadmap

• Phase 0: Architecture and source map
• Phase 1: Core sub-skills (5)
• Phase 2: Main harness + quality gates + degradation
• Phase 3: Knowledge pipeline + tests + schedule
• Phase 4: Testing and validation
• Phase 5: Integration and polish — PRODUCTION READY v1.1.0
• Phase 6: Architectural enhancement & production polish — PRODUCTION READY v1.2.0

See PROJECT-DEVELOPMENT-PHASE-TRACKING.md and CHANGELOG.md.

Why this skill

ADHD environmental-design practitioners face fragmented data, inconsistent methodology, and tools that do not self-improve. This skill unifies authoritative real-time data, recognized environmental-psychology methods, and a continuously-updated academic knowledge base into one evidence-backed, risk-disclosed, personalized workflow.

Safety notice

This skill provides decision-support for home-environment design, not a clinical diagnosis or medical advice. Lighting, acoustic, and sleep interventions are bounded by published reference ranges; recommendations exceeding caution thresholds are flagged for clinical sign-off. Always defer to a qualified clinician for individual health decisions.

License

MIT — see LICENSE.

Citation

@software{adhd-friendly-home-design,
  title  = {adhd-friendly-home-design: ADHD-Friendly Home Space Optimization Advisor},
  year   = {2026},
  version= {1.2.0},
  license= {MIT}
}

Contributing

See CONTRIBUTING.md and CODE_OF_CONDUCT.md.