YouTube Audio - AI Agent Instructions

This repository is AI-Enabled and optimized for Agentic Coding. Before performing any work, you MUST follow these instructions.

Project Overview

YouTube Audio is a Firefox browser extension that allows users to stream only audio from YouTube videos. This saves battery life and bandwidth by disabling video playback while keeping audio.

Technology Stack

Language: JavaScript (ES6+)
Platform: Browser Extension (Firefox/Chrome)
Manifest: WebExtension Manifest V2
APIs: WebRequest, Storage, Tabs, BrowserAction

Required Reading

Before answering any request, you MUST read:

```
docs/agent-instructions/
```
- All files in order (00 → 03)
```
docs/adrs/
```
- Check for past architectural decisions
```
docs/specs/
```
- Review existing specifications
```
docs/architecture/
```
- Understand system design

Core Rules

Rule 1: Documentation First

"No spec, no code."

Before writing code, create or update the specification in
```
docs/specs/
```
After writing code, update
```
docs/history/
```
with a handoff record
Architecture changes require updates to
```
docs/architecture/
```

Rule 2: Check Before You Code

"Avoid regression by learning from history."

Check
```
docs/adrs/
```
for past decisions before proposing changes
Review existing specs to understand design rationale
Search the codebase for similar patterns before creating new ones

Rule 3: Update Documentation

"Code and docs must stay synchronized."

If you modify code, you MUST:

Update the corresponding spec in
```
docs/specs/
```
Update architecture diagrams if structure changes
Create an ADR for significant decisions
Record a handoff in
```
docs/history/
```

Rule 4: Research, Don't Hallucinate

"If you're unsure, search the internet. Do not make up APIs."

Use web search to verify library versions and APIs
Check official documentation before using any external dependency
Validate browser extension API compatibility
Never guess at function signatures or configurations

Coding Standards

JavaScript

Use ES6+ features (const/let, arrow functions, destructuring)
Prefer async/await over callbacks where possible
Use descriptive variable and function names
Add JSDoc comments for public functions

Browser Extension Specifics

Follow WebExtension API conventions
Handle permissions gracefully
Consider cross-browser compatibility (Firefox/Chrome)
Test in private/incognito modes

Testing

90% code coverage minimum for new code
Write tests before or with implementation
Run
```
./scripts/validate.sh
```
before committing

File Structure

youtube-audio/
├── css/                    # Stylesheets
├── docs/                   # Documentation (THE BRAIN)
│   ├── adrs/              # Architecture Decision Records
│   ├── agent-instructions/ # Agent protocols
│   ├── architecture/      # System diagrams
│   ├── history/           # Handoffs and deprecated logic
│   └── specs/             # Technical specifications
├── html/                   # HTML pages
├── img/                    # Icons and images
├── js/                     # JavaScript source
├── scripts/               # Automation scripts
├── tests/                 # Test files
├── .github/               # GitHub configuration
│   ├── agents/            # GitHub agent configs
│   └── workflows/         # CI/CD workflows
└── .claude/               # Claude agent configs

Common Tasks

Adding a New Feature

Write spec in
```
docs/specs/SPEC-NNN-feature.md
```
Update architecture if needed
Write tests first
Implement feature
Verify 90%+ coverage
Run
```
./scripts/validate.sh
```
Record handoff in
```
docs/history/
```

Fixing a Bug

Check
```
docs/history/
```
for related context
Write a failing test that reproduces the bug
Fix the bug
Verify the test passes
Update documentation if behavior changed

Updating Dependencies

Research the update (breaking changes, security fixes)
Create ADR documenting the decision
Update
```
manifest.json
```
or
```
package.json
```
Run full test suite
Update documentation

Quick Reference

Task	Command
Run all validations	`./scripts/validate.sh`
Run linter	`npm run lint`
Run tests	`npm test`
Check coverage	`npm run test:coverage`

Questions?

If you're unsure about something:

Check the documentation in
```
docs/
```
Search the codebase for examples
Research using web search
Ask for clarification rather than guessing

This repository follows the AI-Enabled Repository Standard. Documentation drives code, testing is mandatory, and agents must validate their work.

YouTube Audio - AI Agent Instructions

This repository is AI-Enabled and optimized for Agentic Coding. Before performing any work, you MUST follow these instructions.

Project Overview

YouTube Audio is a Firefox browser extension that allows users to stream only audio from YouTube videos. This saves battery life and bandwidth by disabling video playback while keeping audio.

Technology Stack

Language: JavaScript (ES6+)
Platform: Browser Extension (Firefox/Chrome)
Manifest: WebExtension Manifest V2
APIs: WebRequest, Storage, Tabs, BrowserAction

Required Reading

Before answering any request, you MUST read:

```
docs/agent-instructions/
```
- All files in order (00 → 03)
```
docs/adrs/
```
- Check for past architectural decisions
```
docs/specs/
```
- Review existing specifications
```
docs/architecture/
```
- Understand system design

Core Rules

Rule 1: Documentation First

"No spec, no code."

Before writing code, create or update the specification in
```
docs/specs/
```
After writing code, update
```
docs/history/
```
with a handoff record
Architecture changes require updates to
```
docs/architecture/
```

Rule 2: Check Before You Code

"Avoid regression by learning from history."

Check
```
docs/adrs/
```
for past decisions before proposing changes
Review existing specs to understand design rationale
Search the codebase for similar patterns before creating new ones

Rule 3: Update Documentation

"Code and docs must stay synchronized."

If you modify code, you MUST:

Update the corresponding spec in
```
docs/specs/
```
Update architecture diagrams if structure changes
Create an ADR for significant decisions
Record a handoff in
```
docs/history/
```

Rule 4: Research, Don't Hallucinate

"If you're unsure, search the internet. Do not make up APIs."

Use web search to verify library versions and APIs
Check official documentation before using any external dependency
Validate browser extension API compatibility
Never guess at function signatures or configurations

Coding Standards

JavaScript

Use ES6+ features (const/let, arrow functions, destructuring)
Prefer async/await over callbacks where possible
Use descriptive variable and function names
Add JSDoc comments for public functions

Browser Extension Specifics

Follow WebExtension API conventions
Handle permissions gracefully
Consider cross-browser compatibility (Firefox/Chrome)
Test in private/incognito modes

Testing

90% code coverage minimum for new code
Write tests before or with implementation
Run
```
./scripts/validate.sh
```
before committing

File Structure

youtube-audio/
├── css/                    # Stylesheets
├── docs/                   # Documentation (THE BRAIN)
│   ├── adrs/              # Architecture Decision Records
│   ├── agent-instructions/ # Agent protocols
│   ├── architecture/      # System diagrams
│   ├── history/           # Handoffs and deprecated logic
│   └── specs/             # Technical specifications
├── html/                   # HTML pages
├── img/                    # Icons and images
├── js/                     # JavaScript source
├── scripts/               # Automation scripts
├── tests/                 # Test files
├── .github/               # GitHub configuration
│   ├── agents/            # GitHub agent configs
│   └── workflows/         # CI/CD workflows
└── .claude/               # Claude agent configs

Common Tasks

Adding a New Feature

Write spec in
```
docs/specs/SPEC-NNN-feature.md
```
Update architecture if needed
Write tests first
Implement feature
Verify 90%+ coverage
Run
```
./scripts/validate.sh
```
Record handoff in
```
docs/history/
```

Fixing a Bug

Check
```
docs/history/
```
for related context
Write a failing test that reproduces the bug
Fix the bug
Verify the test passes
Update documentation if behavior changed

Updating Dependencies

Research the update (breaking changes, security fixes)
Create ADR documenting the decision
Update
```
manifest.json
```
or
```
package.json
```
Run full test suite
Update documentation

Quick Reference

Task	Command
Run all validations	`./scripts/validate.sh`
Run linter	`npm run lint`
Run tests	`npm test`
Check coverage	`npm run test:coverage`

Questions?

If you're unsure about something:

Check the documentation in
```
docs/
```
Search the codebase for examples
Research using web search
Ask for clarification rather than guessing

This repository follows the AI-Enabled Repository Standard. Documentation drives code, testing is mandatory, and agents must validate their work.

YouTube Audio - AI Agent Instructions

Related Skills

Markdown Converter

Nano Banana Pro

1password