agentic-dev 0.1.0 → 0.2.1

package/.codex/agents/gitops.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are the GitOps/deployment sub-agent.
+
+Mission:
+- Own compose, CI/CD, and deployment wiring.
+- Keep main-to-DEV and tag-to-prod release flows deterministic.
+- Prefer explicit and inspectable automation.
+"""

package/.codex/agents/orchestrator.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are the orchestration sub-agent.
+
+Mission:
+- Improve orchestration flows and operational safety.
+- Keep start, stop, deploy, and verification actions deterministic.
+- Prefer bounded automation over ad hoc behavior.
+"""

package/.codex/agents/quality.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are the quality sub-agent.
+
+Mission:
+- Run validation gates and find regressions.
+- Report concrete failing surfaces and likely fixes.
+- Keep verification concise and actionable.
+"""

package/.codex/agents/runtime.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are the runtime sub-agent.
+
+Mission:
+- Refactor runtime and application wiring while preserving behavior.
+- Prefer small, testable, reversible changes.
+- Keep implementation generic and reusable.
+"""

package/.codex/agents/security.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+developer_instructions = """
+You are the security sub-agent.
+
+Mission:
+- Audit security and operational regression risk.
+- Focus on reproducible issues and concrete mitigation guidance.
+- Avoid speculative findings.
+"""

package/.codex/agents/specs.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+developer_instructions = """
+You are the specs sub-agent.
+
+Mission:
+- Validate SDD and specification consistency.
+- Find drift between implementation and declared contracts.
+- Return concrete file references and minimal corrections.
+"""

package/.codex/agents/ui.toml

@@ -0,0 +1,11 @@
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "workspace-write"
+developer_instructions = """
+You are the UI sub-agent.
+
+Mission:
+- Keep UI contracts aligned with backend APIs and design intent.
+- Prefer minimal, compatible changes.
+- Preserve reusable component surfaces.
+"""

package/.codex/config.toml

@@ -0,0 +1,46 @@
+[features]
+multi_agent = true
+
+[agents]
+max_threads = 10
+max_depth = 1
+
+[agents.architecture]
+description = "Drive high-level architecture, boundaries, and migration decisions."
+config_file = "agents/architecture.toml"
+
+[agents.runtime]
+description = "Refactor runtime and application wiring while preserving behavior."
+config_file = "agents/runtime.toml"
+
+[agents.gitops]
+description = "Own CI/CD, compose, and deployment wiring."
+config_file = "agents/gitops.toml"
+
+[agents.quality]
+description = "Run validation gates and identify regressions."
+config_file = "agents/quality.toml"
+
+[agents.api]
+description = "Own API boundary contracts and backward compatibility."
+config_file = "agents/api.toml"
+
+[agents.orchestrator]
+description = "Improve orchestration flows and operational safety."
+config_file = "agents/orchestrator.toml"
+
+[agents.ci]
+description = "Maintain pipeline policy and release path integrity."
+config_file = "agents/ci.toml"
+
+[agents.specs]
+description = "Validate SDD and specification consistency."
+config_file = "agents/specs.toml"
+
+[agents.ui]
+description = "Own UI contracts, hooks, and frontend integration surfaces."
+config_file = "agents/ui.toml"
+
+[agents.security]
+description = "Audit security and operational regression risk."
+config_file = "agents/security.toml"

package/.codex/skills/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: otro
+description: OTRO (Overlap-Tolerant Residual Orchestration) root alias for the canonical template skill surface.
+---
+
+# OTRO Alias
+
+이 파일은 root alias다. canonical OTRO skill body와 scripts/references/schemas는 [`otro/SKILL.md`](./otro/SKILL.md)를 기준으로 사용한다.
+
+## Rule
+
+- OTRO 실행 시 root 중복 자산이 아니라 `otro/` 하위 canonical 자산만 사용한다.
+- `sdd-development`, `ralph-loop`, `planning-with-files`는 별도 skill surface로 유지한다.

package/.codex/skills/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "OTRO"
+  short_description: "Overlap-tolerant residual orchestration"
+  default_prompt: "Use $OTRO to analyze the repository globally, dispatch bounded Codex workers, reconcile residual overlap, and replan until repository-level gates are satisfied."

package/.codex/skills/commit/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: commit
+description: Write conventional commit messages with type, scope, and subject when the user wants to commit changes or save work.
+---
+
+# Git Commit
+
+Creates git commits following Conventional Commits format with proper type, scope, and subject.
+
+## Quick Start
+
+```bash
+# 1. Stage changes
+git add <files>  # or: git add -A
+
+# 2. Create commit (branch commit format)
+git commit -m "type(scope): subject
+
+Body explaining HOW and WHY.
+Reference: Task X.Y, Req N"
+```
+
+## Commit Types
+
+### Regular Branch Commits (During Development)
+
+**Format**: `type(scope): subject`
+
+| Type | Purpose |
+|------|---------|
+| `feat` | New feature or functionality |
+| `fix` | Bug fix or issue resolution |
+| `refactor` | Code refactoring without behavior change |
+| `perf` | Performance improvements |
+| `test` | Test additions or modifications |
+| `ci` | CI/CD configuration changes |
+| `docs` | Documentation updates |
+| `chore` | Maintenance, dependencies, tooling |
+| `style` | Code formatting, linting (non-functional) |
+| `security` | Security vulnerability fixes or hardening |
+
+### Scope (Required, kebab-case)
+
+Examples: `validation`, `auth`, `cookie-service`, `template`, `config`, `tests`, `api`
+
+### Subject Line Rules
+
+- Max 50 characters after colon
+- Present tense imperative: add, implement, fix, improve, enhance, refactor, remove, prevent
+- NO period at the end
+- Specific and descriptive - state WHAT, not WHY
+
+## Core Workflow
+
+### 1. Review Changes
+
+```bash
+git status
+git diff --staged  # if already staged
+git diff           # if not staged
+```
+
+### 2. Stage Files
+
+```bash
+git add <specific-files>  # preferred
+# or
+git add -A  # all changes
+```
+
+**NEVER commit**:
+- `.env`, `credentials.json`, secrets
+- `node_modules/`, `__pycache__/`, `.venv/`
+- Large binary files without explicit approval
+
+### 3. Create Commit
+
+**Simple change**:
+```bash
+git commit -m "fix(auth): use hmac.compare_digest for secure comparison"
+```
+
+**Complex change (with body)**:
+```bash
+git commit -m "$(cat <<'EOF'
+feat(validation): add URLValidator with domain whitelist
+
+Implement URLValidator class supporting:
+- Domain whitelist enforcement (youtube.com, youtu.be)
+- Dangerous scheme blocking (javascript, data, file)
+- URL parsing with embedded credentials handling
+
+Addresses Requirement 31: Input validation
+Part of Task 5.1: Input Validation Utilities
+EOF
+)"
+```
+
+### 4. Verify Commit
+
+```bash
+git log -1 --format="%h %s"
+git show --stat HEAD
+```
+
+## Body Format (Recommended for Complex Changes)
+
+```
+<blank line>
+Explain HOW and WHY the change was made.
+- Use bullet points for multiple items
+- Wrap at 72 characters
+
+Reference: Task X.Y
+Addresses: Req N
+```
+
+## Git Trailers
+
+| Trailer | Purpose |
+|---------|---------|
+| `Fixes #N` | Links and closes issue on merge |
+| `Closes #N` | Same as Fixes |
+| `Co-authored-by: Name <email>` | Credit co-contributors |
+
+Place trailers at end of body after blank line. See `references/commit_examples.md` for examples.
+
+## Breaking Changes
+
+For incompatible API/behavior changes, use `!` after scope OR `BREAKING CHANGE:` footer:
+
+```
+feat(api)!: change response format to JSON:API
+
+BREAKING CHANGE: Response envelope changed from `{ data }` to `{ data: { type, id, attributes } }`.
+```
+
+Triggers major version bump in semantic-release.
+
+## Merge Commits (PR Closure)
+
+For PRs, use extended description with sections:
+
+```bash
+gh pr create --title "feat(security): implement input validation (Task 5)" --body "$(cat <<'EOF'
+## Summary
+- Input validation utilities (URLValidator, FormatValidator)
+- Secure template processor with path traversal prevention
+- API key authentication middleware
+
+## Task Breakdown
+Task 5.1: Input Validation - URLValidator, FormatValidator
+Task 5.2: Template Processing - Path traversal prevention
+Task 5.3: API Key Auth - Multi-key support, excluded paths
+Task 5.4: Security Tests - 102 path traversal tests
+
+## Requirements Covered
+Req 7, Req 9, Req 31, Req 33
+
+## Test Coverage
+- All 473 tests passing
+- Coverage: 93%
+- Pre-commit checks: passing
+EOF
+)"
+```
+
+## Integration with Other Skills
+
+### From github-pr-review
+
+When fixing review comments, use this format:
+
+```bash
+git commit -m "fix(scope): address review comment #ID
+
+Brief explanation of what was wrong and how it's fixed.
+Addresses review comment #123456789."
+```
+
+### From github-pr-creation
+
+Before creating PR, ensure all commits follow this format. The PR skill will:
+1. Analyze commits for proper format
+2. Extract types for PR labels
+3. Build PR description from commit bodies
+
+## Important Rules
+
+- **ALWAYS** include scope in parentheses
+- **ALWAYS** use present tense imperative verb
+- **NEVER** end subject with period
+- **NEVER** commit secrets or credentials
+- **NEVER** use generic messages ("update code", "fix bug", "changes")
+- **NEVER** exceed 50 chars in subject line
+- Group related changes -> single focused commit
+
+## Examples
+
+**Good**:
+```
+feat(validation): add URLValidator with domain whitelist
+fix(auth): use hmac.compare_digest for secure key comparison
+refactor(template): consolidate filename sanitization logic
+test(security): add 102 path traversal prevention tests
+```
+
+**Bad**:
+```
+update validation code           # no type, no scope, vague
+feat: add stuff                  # missing scope, too vague
+fix(auth): fix bug               # circular, not specific
+chore: make changes              # missing scope, vague
+feat(security): improve things.  # has period, vague
+```
+
+## References
+
+- `references/commit_examples.md` - Extended examples by type

package/.codex/skills/commit/references/commit_examples.md

@@ -0,0 +1,292 @@
+# Commit Examples by Type
+
+Extended examples for each commit type with body content.
+
+## feat - New Features
+
+```
+feat(validation): add URLValidator with domain whitelist
+
+Implement URLValidator class supporting:
+- Domain whitelist enforcement (youtube.com, youtu.be, m.youtube.com)
+- Dangerous scheme blocking (javascript, data, file)
+- URL parsing with embedded credentials handling
+- Port number validation (1-65535)
+
+Addresses Requirement 31: Input validation
+Part of Task 5.1: Input Validation Utilities
+```
+
+```
+feat(api): add video metadata endpoint
+
+New GET /api/v1/videos/{id}/metadata endpoint:
+- Returns title, duration, formats, thumbnails
+- Supports format filtering via query params
+- Implements caching with 5-minute TTL
+
+Part of Task 6.2: API Endpoints
+```
+
+## fix - Bug Fixes
+
+```
+fix(auth): use hmac.compare_digest for secure key comparison
+
+Replace direct string equality with hmac.compare_digest to prevent
+timing attacks on API key validation. Ensures constant-time comparison
+regardless of key length or content.
+
+Addresses security best practice for sensitive data comparison
+```
+
+```
+fix(download): handle network timeout during video fetch
+
+Add retry logic with exponential backoff for network failures:
+- Max 3 attempts with delays [2, 4, 8] seconds
+- Classify retriable errors (5xx, timeout, connection)
+- Log each retry attempt with remaining count
+
+Fixes issue where downloads would fail silently on flaky connections
+```
+
+## refactor - Code Improvements
+
+```
+refactor(template): consolidate filename sanitization logic
+
+Extract common sanitization patterns into helper methods:
+- Path traversal prevention (.., /, absolute paths)
+- Special character removal (control chars, null bytes)
+- Windows reserved name handling (CON, PRN, LPT1-9, etc)
+
+Improves code maintainability and reduces duplication
+```
+
+```
+refactor(providers): extract common yt-dlp options builder
+
+Move duplicated option building from get_info/download to
+_build_base_options helper. Reduces code duplication and ensures
+consistent option handling across all provider methods.
+
+No behavior change, pure refactoring
+```
+
+## test - Test Changes
+
+```
+test(security): add 102 path traversal prevention tests
+
+Comprehensive test coverage for TemplateProcessor including:
+- Basic path traversal attempts (.., /)
+- URL-encoded variants (%2e%2e, %2f)
+- Unicode/UTF-8 bypass attempts
+- Windows edge cases (backslashes, drive letters)
+
+Part of Task 5.4: Security Test Suite
+```
+
+```
+test(validation): add parametrized URL validation tests
+
+Add 25 test cases covering:
+- Valid YouTube URL formats (watch, shorts, embed, youtu.be)
+- Invalid domains (vimeo, dailymotion)
+- Malformed URLs (no scheme, wrong port)
+- Edge cases (trailing slashes, query params)
+
+Coverage for URLValidator: 98%
+```
+
+## perf - Performance
+
+```
+perf(cache): implement LRU eviction for metadata cache
+
+Replace dict-based cache with LRU implementation:
+- Max 1000 entries with automatic eviction
+- 40% memory reduction under high load
+- Sub-millisecond lookup times maintained
+
+Addresses memory growth issue in long-running instances
+```
+
+## security - Security Fixes
+
+```
+security(cookie): validate cookie file integrity before use
+
+Add SHA256 checksum verification for cookie files:
+- Compute hash on first load, store in memory
+- Verify hash before each use
+- Reject modified files with clear error message
+
+Prevents use of tampered cookie files
+Addresses Requirement 33: Security validation
+```
+
+## ci - CI/CD Changes
+
+```
+ci(github): add security scanning to PR workflow
+
+Enable Bandit security scanner in GitHub Actions:
+- Run on all Python files
+- Fail on HIGH/CRITICAL findings
+- Cache virtualenv for faster runs
+
+Part of Task 15.3: Basic security validation
+```
+
+## docs - Documentation
+
+```
+docs(api): add OpenAPI description for download endpoint
+
+Document /api/v1/download endpoint:
+- Request body schema with format options
+- Response codes (200, 400, 401, 404, 500)
+- Example requests and responses
+
+Improves API documentation for consumers
+```
+
+## chore - Maintenance
+
+```
+chore(deps): update yt-dlp to 2024.12.06
+
+Update yt-dlp from 2024.11.15 to 2024.12.06:
+- Fixes YouTube throttling detection
+- Adds support for new Instagram format
+- Improves error messages for geo-blocked content
+
+No breaking changes expected
+```
+
+## style - Formatting
+
+```
+style(providers): apply black formatting to youtube.py
+
+Apply black formatter with 88 char line length.
+No functional changes, formatting only.
+```
+
+## Merge Commit Examples
+
+### Feature Branch to Develop
+
+```
+Merge pull request #5 from fvadicamo/feature/input-validation-security
+
+feat(security): implement input validation and security (Task 5)
+
+Merges comprehensive security implementation (Task 5) into develop:
+- Input validation utilities (URLValidator, FormatValidator, ParameterValidator)
+- Secure template processor with path traversal prevention
+- API key authentication middleware with multi-key support
+- 473 tests with 93% coverage
+
+Task 5.1: Input Validation Utilities
+- URLValidator: Domain whitelist (youtube.com, youtu.be), dangerous scheme blocking
+- FormatValidator: yt-dlp format ID validation with regex and selectors
+- ParameterValidator: Audio quality/format and language code validation
+
+Task 5.2: Template Processor
+- Path traversal prevention (.., /, absolute paths, URL encoding)
+- Filename sanitization (illegal chars, control chars, null bytes)
+- Windows reserved names handling (CON, PRN, AUX, NUL, COM1-9, LPT1-9)
+- Collision handling with numeric suffix, max length 200 chars
+
+Task 5.3: API Key Authentication
+- APIKeyAuth class with multi-key support
+- Excluded paths for health/doc endpoints
+- Secure hashing for logging (SHA256 first 8 chars)
+- FastAPI dependency injection integration
+
+Task 5.4: Security Tests
+- 102 path traversal prevention tests with edge cases
+- URL validation tests with malicious inputs
+- API key authentication and credential tests
+- Sensitive data redaction verification
+
+Requirements Covered:
+- Req 7: Output template processing with security
+- Req 9: API key authentication
+- Req 31: Input validation
+- Req 33: Security (secure comparison, log redaction)
+
+Test Coverage:
+- All 473 tests passing
+- Coverage: 93% (exceeds 80% minimum)
+- Pre-commit checks: all passing
+```
+
+### Develop to Main (Release)
+
+```
+Merge pull request #10 from fvadicamo/develop
+
+release: v0.1.0 - MVP with YouTube provider
+
+First stable release with core functionality:
+- YouTube video info, formats, download, audio extraction
+- Cookie-based authentication for age-restricted content
+- API key authentication
+- Input validation and security hardening
+- 500+ tests with 92% coverage
+
+Breaking Changes: None (initial release)
+
+Features:
+- GET /api/v1/info - Video metadata
+- GET /api/v1/formats - Available formats
+- POST /api/v1/download - Video/audio download
+- Cookie file support for authenticated requests
+
+Documentation:
+- API documentation at /docs (Swagger UI)
+- OpenAPI spec at /openapi.json
+```
+
+## Commits with Trailers
+
+### Single Issue
+```
+fix(validation): prevent XSS in user input
+
+Escape HTML entities before rendering.
+
+Fixes #78
+```
+
+### Multiple Issues + Co-author
+```
+fix(auth): resolve session and token issues
+
+- Fix session expiry not triggering logout
+- Fix token refresh race condition
+
+Fixes #101
+Fixes #103
+Co-authored-by: Bob <bob@example.com>
+```
+
+## Breaking Changes
+
+### With ! Notation
+```
+feat(api)!: migrate to v2 endpoints
+
+BREAKING CHANGE: /api/v1/* endpoints removed. Update base URL to /api/v2/.
+```
+
+### Config Breaking Change
+```
+chore(config)!: rename environment variables
+
+BREAKING CHANGE: DATABASE_URL -> APP_DATABASE_URL, API_KEY -> APP_API_KEY
+```