# Therapeutic Sound Space Design

> Sound Therapy Space Design (Curated Playlists & Frequencies) — Therapeutic Sound-Space Design & Applied Psychoacoustics evidence-backed analysis & decision-support harness. Use this skill whenever the user needs to design therapeutic sound spaces, create curated playlists for therapeutic goals, analyze acoustic environments for therapy, work with binaural beats or solfeggio frequencies, needs mus…

- **Type:** Skill
- **Install:** `agentstack add skill-dungnotnull-therapeutic-sound-space-design-agent-skill-therapeutic-sound-space-design-agent-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dungnotnull](https://agentstack.voostack.com/s/dungnotnull)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** https://github.com/dungnotnull/therapeutic-sound-space-design-agent-skill

## Install

```sh
agentstack add skill-dungnotnull-therapeutic-sound-space-design-agent-skill-therapeutic-sound-space-design-agent-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Therapeutic Sound-Space Design Skill

## Overview

This is a **production-grade** Claude Code skill for **Therapeutic Sound-Space Design & Applied Psychoacoustics**. It transforms Claude into a domain expert that delivers structured, evidence-backed outputs by combining real-time data aggregation, recognized domain methods, and academic research into a single orchestrated workflow.

## What This Skill Does

When invoked, this skill executes a **6-step analytical pipeline**:

1. **Requirements Gathering** — Clarify therapeutic goals, user profiles, space constraints, and analysis language
2. **Evidence Collection** — Fetch authoritative real-time data from domain sources, standards, and recent research
3. **Core Analysis** — Design sound-therapy protocols, playlists, acoustic treatments, and spatial audio configurations
4. **Knowledge Query** — Surface academic evidence from the living knowledge base with tier labels
5. **Advisory Synthesis** — Generate risk-disclosed conclusions with evidence chains and remediation roadmaps
6. **Quality Gate Enforcement** — Verify 10 quality criteria with automatic fixes and graceful degradation

## Key Features

### Production-Grade Capabilities
- **State Management**: Persistent session state with recovery and context budget management
- **Error Handling**: Circuit breakers, retry mechanisms, and structured error classification
- **Monitoring**: Prometheus metrics, health checks, and performance monitoring
- **Configuration Management**: Environment variable support, validation, and secrets management
- **Bilingual Support**: Full English/Vietnamese language detection and output
- **Self-Improving**: Weekly academic crawl pipeline continuously updates the knowledge base

### Quality Assurance
- **10 Quality Gates**: Universal (U1-U6) plus domain-specific (G1-G4) validation
- **Evidence Hierarchy**: 4-tier system (Tier 1: Peer-reviewed → Tier 4: General references)
- **Graceful Degradation**: 5 degradation levels with explicit limitation notices
- **Auto-Recovery**: Automatic fixes with 2-retry maximum per gate

## When to Use This Skill

Invoke this skill when the user asks about:

**Core Design Tasks:**
- Design a therapeutic sound space for [goal] (relaxation, focus, sleep, pain management, etc.)
- Create a curated playlist for [therapeutic outcome]
- Analyze the acoustic properties of [space] for therapy use
- Design room acoustics for [clinical/wellness setting]
- Select frequency protocols for [specific therapeutic goal]

**Technical Applications:**
- Binaural beat protocols for [state/condition]
- Solfeggio frequency applications for [purpose]
- Spatial audio configuration for therapy spaces
- RT60 and acoustic treatment recommendations
- Sound isolation requirements for therapy spaces

**Clinical & Evidence-Based:**
- Music therapy interventions for [condition/population]
- Psychoacoustic applications for [wellness goal]
- Evidence-based sound environment design
- Outcome measurement protocols for sound therapy
- Safety guidelines for therapeutic sound applications

**Research & Analysis:**
- Current research on [specific sound therapy topic]
- Compare acoustic treatment options for [space type]
- Academic evidence for [frequency/protocol]
- Best practices for [therapeutic sound scenario]

## Input/Output Schema

### Input Format

The skill accepts natural language queries. Examples:

```json
{
  "query": "Design a relaxation room for stress reduction in a corporate wellness center",
  "context": {
    "space": "20x15 ft room with 10 ft ceiling",
    "users": "adult employees, 18-65, mixed experience",
    "constraints": ["budget: $5000", "existing HVAC noise present"],
    "language": "en"
  }
}
```

### Output Format

The skill delivers a structured report following this template:

```markdown
# [Analysis Report Title]

## Executive Summary
[Brief overview of findings and recommendation]

## Inputs & Scope
[Requirements, space parameters, user profile]

## Evidence Base
[Sources with tier labels, citation counts]

## Sound-Space Design
[Frequency protocols, playlist architecture]

## Room Acoustics
[RT60 analysis, absorption strategy, treatment recommendations]

## Spatial Audio Configuration
[Speaker layout, imaging, localization parameters]

## Outcome Measurement
[Clinical instruments, assessment protocols]

## Safety & Limitations
[Risk assessment, contraindications, usage guidelines]

## Evidence Chain
[All claims traced to sources with tier labels]

## Recommendation
[Primary verdict with confidence level]

## Implementation Roadmap
[Step-by-step guidance with timelines]

## Appendix
[Technical calculations, reference tables]
```

## Skill Architecture

### Modular Sub-Skills

The skill orchestrates 6 specialized sub-skills:

| Sub-Skill | Purpose | Key Outputs |
|----------|---------|-------------|
| `sub-gather-requirements` | Intake specialist | Structured requirements object |
| `sub-evidence-collector` | Data librarian | Evidence bundle with tier labels |
| `sub-core-analysis` | Sound-space designer | Protocols, playlists, acoustics |
| `sub-knowledge-updater` | Research librarian | Academic citations with coverage |
| `sub-advisor` | Senior advisor | Risk-disclosed verdicts |

### State Management

The skill maintains a session state object throughout execution:

```yaml
session:
  id: "tsd-{timestamp}-{random4}"
  lang: "vi" | "en"
  degradation_level: 0-4
  steps_completed: []
  errors_encountered: []
  retry_counts: {}
  gate_results: {}
```

This enables:
- Context passing between pipeline steps
- Error recovery with degradation tracking
- Token budget management
- Session persistence and recovery

## Quality Gates

### Universal Gates (U1-U6)

| Gate | Criterion | Purpose |
|------|-----------|---------|
| U1 | ≥3 sources cited, ≥1 academic/authoritative | Evidence breadth |
| U2 | Safety/risk/limitation disclosure present | User protection |
| U3 | Evidence hierarchy stated per source | Transparency |
| U4 | Language matches user preference | Localization |
| U5 | Complete output template | Completeness |
| U6 | Claims traceable to sources | Accountability |

### Domain Gates (G1-G4)

| Gate | Criterion | Purpose |
|------|-----------|---------|
| G1 | Goal-aligned frequency protocol selection | Clinical alignment |
| G2 | Room acoustics designed with RT60 | Technical rigor |
| G3 | Outcome measurement with safety limits | Evidence-based practice |
| G4 | Music-therapy academic evidence cited | Domain grounding |

### Auto-Fix Mechanisms

Each gate has defined auto-fix procedures:
- **U1**: Fetch additional sources if 

# Clean old sessions
python tools/state_manager.py cleanup --days 7
```

### Monitoring
```bash
# Health check
python tools/monitoring.py health --export health.json

# Metrics export
python tools/monitoring.py metrics --format prometheus --export metrics.prom

# Performance monitoring
python tools/monitoring.py performance --threshold 5000
```

### Configuration
```bash
# Validate configuration
python tools/config_manager.py validate

# Export configuration
python tools/config_manager.py export --include-secrets

# Test environment
python tools/config_manager.py test-env
```

### Testing
```bash
# Integration tests
python tools/integration_tests.py --output test_results.json

# Performance tests
python tools/performance_tests.py --quick

# Scenario tests
python tools/run_test_scenarios.py --all
```

## Bilingual Support

The skill automatically detects and supports English and Vietnamese:

### Detection Triggers
- **Vietnamese characters**: à á ả ã ạ ă â đ è é ê ì í ò ó ô ơ ù ú ư ý
- **Vietnamese words**: "thiết kế", "âm thanh", "trị liệu", "không gian", "tần số"
- **English**: Default when no Vietnamese detected

### Translation Coverage
All output sections, field labels, verdict categories, and limitation banners are translated:
- Report structure (14 sections)
- Verdict taxonomy (4 categories)
- Quality gate messages
- Error recovery procedures
- Technical terminology

## Development & Extension

### Adding New Sub-Skills

1. Create `skills/sub-.md` with frontmatter
2. Define role, workflow, tools, output format, quality gates
3. Add to `skills/main.md` sub-skills list
4. Update harness flow to invoke the sub-skill
5. Add test scenarios to `tests/test-scenarios.md`

### Modifying Quality Gates

1. Update gate definitions in `skills/main.md`
2. Add auto-fix procedures
3. Update enforcement logic
4. Add test coverage for new gate
5. Document in `CLAUDE.md`

### Extending Knowledge Base

1. Add new section to `SECOND-KNOWLEDGE-BRAIN.md`
2. Update `KNOWLEDGE_CONFIG` in `tools/knowledge_updater.py`
3. Add crawl sources for new domain
4. Update scoring weights if needed
5. Test with `--dry-run` flag

## Testing

### Unit Tests
```bash
python tools/test_knowledge_updater.py
```
25+ tests covering hash dedup, scoring, formatting, config validation.

### Integration Tests
```bash
python tools/integration_tests.py
```
End-to-end testing of all system components with real data flows.

### Performance Tests
```bash
python tools/performance_tests.py --quick
```
Load testing, resource monitoring, and benchmarking.

### Scenario Tests
```bash
python tools/run_test_scenarios.py --all
```
6 comprehensive scenarios covering all therapeutic goals, verdict categories, and degradation levels.

## Deployment

### Docker Deployment
```bash
# Build image
docker build -t therapeutic-sound-space-design:latest .

# Run container
docker run -p 8080:8080 -p 9090:9090 \
  -e TSD_STATE_DIR=/state \
  -e TSD_METRICS_ENABLED=true \
  therapeutic-sound-space-design:latest
```

### Systemd Service
```bash
# Install service
sudo cp systemd/therapeutic-sound-space-design.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable therapeutic-sound-space-design
sudo systemctl start therapeutic-sound-space-design
```

See `docs/DEPLOYMENT_GUIDE.md` for comprehensive deployment procedures.

## Monitoring & Observability

### Health Endpoints
- `/health` — Overall system health
- `/health/{check}` — Specific health check (disk_space, memory, api)
- `/metrics` — Prometheus metrics

### Key Metrics
- Session success rate
- Average execution time
- Gate failure rates
- Knowledge update success
- API circuit breaker state
- Token usage per session

### Logging
Structured logs with levels (DEBUG, INFO, WARNING, ERROR, CRITICAL):
- `logs/knowledge_update.log` — Knowledge pipeline
- `logs/session.log` — Session execution
- `logs/error.log` — Error events

See `docs/MONITORING_RUNBOOK.md` for operational procedures.

## Documentation

- **[API Documentation](docs/API_DOCUMENTATION.md)** — Complete API reference
- **[Deployment Guide](docs/DEPLOYMENT_GUIDE.md)** — Production deployment
- **[Monitoring Runbook](docs/MONITORING_RUNBOOK.md)** — Operations guide
- **[Contributing Guide](CONTRIBUTING.md)** — Development guidelines
- **[Architecture](PROJECT-detail.md)** — Technical specification

## License

MIT License — see [LICENSE](LICENSE).

## Citation

```bibtex
@software{therapeutic-sound-space-design,
  title = {therapeutic-sound-space-design: Sound Therapy Space Design},
  author = {therapeutic-sound-space-design contributors},
  year = {2026},
  version = {1.0.0},
  url = {https://github.com/contributors/therapeutic-sound-space-design}
}
```

---

**Version**: 1.0.0 | **Status**: Production Ready | **Last Updated**: 2026-07-27

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [dungnotnull](https://github.com/dungnotnull)
- **Source:** [dungnotnull/therapeutic-sound-space-design-agent-skill](https://github.com/dungnotnull/therapeutic-sound-space-design-agent-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dungnotnull-therapeutic-sound-space-design-agent-skill-therapeutic-sound-space-design-agent-skill
- Seller: https://agentstack.voostack.com/s/dungnotnull
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.