Part 1 - Core refactor: unify tool/platform APIs and harden launch validation

.codex/skills/feature-architect/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: feature-architect
+description: "Produce complete feature architecture deliverables from informal requests. Use when Codex must convert a rough feature idea into implementation-ready planning documents: product requirements (`prd.md`), functional design (`fdd.md`), and a phased execution plan (`plan.md`) with checkbox task tracking. Prioritize Elixir, Erlang, OTP/BEAM, and web architecture best practices."
+---
+
+# Feature Architect
+
+Create a cohesive architecture package that an engineer can implement without re-interpreting intent.
+
+## Workflow
+
+1. Capture feature intent
+- Parse the informal request into: problem, users, desired outcomes, constraints, and unknowns.
+- State assumptions explicitly when inputs are missing.
+- Ask concise follow-up questions only when unknowns materially change design or scope.
+
+2. Define scope and boundaries
+- Separate in-scope work from out-of-scope work.
+- Define release slices (MVP vs later phases).
+- Identify dependencies, risks, migration needs, and rollout constraints.
+
+3. Design for Elixir/OTP web systems
+- Use [references/elixir-architecture.md](references/elixir-architecture.md) to choose runtime structure, process boundaries, supervision strategy, persistence model, and observability.
+- Prefer fault-tolerant process design, clear module boundaries, and explicit contracts between contexts.
+
+4. Produce required outputs
+- Create a feature folder at `docs/features/<feature-slug>/`.
+- Generate exactly three files in that folder: `prd.md`, `fdd.md`, and `plan.md`.
+- Use [references/document-templates.md](references/document-templates.md) as the default structure.
+- Keep all three documents internally consistent for naming, scope, and acceptance criteria.
+
+5. Validate package quality
+- Verify every functional requirement maps to design elements and implementation tasks.
+- Ensure non-functional requirements (performance, reliability, security, operability) have concrete implementation considerations.
+- Ensure plan tasks are actionable, testable, and sequenced.
+- Ensure phases are cohesive units of functionality that are intended to be implemented in order.
+- Ensure the final phase is manual QA acceptance testing.
+- For large features, define PR groups that bundle one or more sequential phases for incremental delivery.
+
+## Output Requirements
+
+Always produce:
+
+1. `docs/features/<feature-slug>/prd.md`
+- Define user problem, business goals, target users, use cases, functional requirements, non-functional requirements, success metrics, and acceptance criteria.
+
+2. `docs/features/<feature-slug>/fdd.md`
+- Define architecture, component/module responsibilities, data model changes, interfaces/contracts, runtime/process behavior, error handling, observability, security posture, and test strategy.
+
+3. `docs/features/<feature-slug>/plan.md`
+- Define phased implementation with checkbox tasks.
+- Use unchecked markdown checkboxes for pending work: `- [ ] Task`.
+- Group tasks by phase and include explicit deliverables and verification steps.
+- Order phases sequentially and mark each phase as a cohesive unit of functionality.
+- Include a final manual QA acceptance testing phase.
+- If needed, include a PR grouping section mapping phases to PR groups for oversized features.
+- Keep tasks granular enough that progress can be tracked during implementation.
+
+## Standards
+
+- Design for maintainability, fault tolerance, and operational clarity.
+- Prefer explicit tradeoff notes when multiple approaches are viable.
+- Avoid vague tasks such as "implement feature"; break into concrete outcomes.
+- Tie each phase to measurable completion criteria.
+- Keep the architecture realistic for the current codebase and team maturity.

.codex/skills/feature-architect/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Feature Architect"
+  short_description: "Draft PRD, FDD, and phased plan docs for Elixir apps."
+  default_prompt: "Turn this feature idea into prd.md, fdd.md, and plan.md with phased checkbox tasks for implementation."

.codex/skills/feature-architect/references/document-templates.md

@@ -0,0 +1,179 @@
+# Feature Architect Templates
+
+Use these templates as defaults unless the user specifies a different format.
+
+## `prd.md`
+
+```markdown
+# Product Requirements Document
+
+## 1. Feature Summary
+- Name:
+- Owner:
+- Last Updated:
+- Status:
+
+## 2. Problem Statement
+- Current pain:
+- Why now:
+
+## 3. Goals and Non-Goals
+### Goals
+- 
+
+### Non-Goals
+- 
+
+## 4. Users and Primary Use Cases
+- Personas:
+- Core scenarios:
+
+## 5. Functional Requirements
+1. 
+2. 
+
+## 6. Non-Functional Requirements
+- Reliability:
+- Performance:
+- Security/Compliance:
+- Observability:
+
+## 7. Success Metrics
+- Product metrics:
+- Technical metrics:
+
+## 8. Dependencies and Constraints
+- Internal dependencies:
+- External dependencies:
+- Constraints:
+
+## 9. Risks and Mitigations
+- Risk:
+- Mitigation:
+
+## 10. Acceptance Criteria
+1. Given/When/Then...
+2. 
+```
+
+## `fdd.md`
+
+```markdown
+# Functional Design Document
+
+## 1. Design Overview
+- Scope covered:
+- Assumptions:
+
+## 2. System Context and Boundaries
+- In-scope components:
+- Out-of-scope components:
+
+## 3. Architecture
+- High-level flow:
+- Context/module responsibilities:
+- Supervision tree impact:
+
+## 4. Data Design
+- Schema changes:
+- Data lifecycle:
+- Migration/backfill strategy:
+
+## 5. Interfaces and Contracts
+- Internal APIs:
+- External APIs/webhooks:
+- Event/message formats:
+
+## 6. Runtime Behavior
+- Process model:
+- Concurrency model:
+- Failure handling/retries:
+- Timeouts/circuit breakers:
+
+## 7. Security and Compliance
+- AuthN/AuthZ impact:
+- Data protection:
+- Audit/logging requirements:
+
+## 8. Observability and Operations
+- Metrics:
+- Logs:
+- Tracing:
+- Alerts/runbooks:
+
+## 9. Testing Strategy
+- Unit:
+- Integration:
+- Contract:
+- End-to-end:
+- Load/failure:
+
+## 10. Open Questions
+- 
+```
+
+## `plan.md`
+
+```markdown
+# Implementation Plan
+
+## Phase 0 - Alignment and Readiness
+### Deliverables
+- Approved requirements and design baseline
+
+### Tasks
+- [ ] Confirm scope, assumptions, and dependencies
+- [ ] Finalize acceptance criteria and test approach
+- [ ] Identify rollout and rollback constraints
+
+### Verification
+- [ ] PRD and FDD approved
+- [ ] Risks have owners and mitigations
+
+## Phase 1 - Foundations
+### Deliverables
+- Core scaffolding and contracts
+
+### Tasks
+- [ ] Implement core domain modules/contexts
+- [ ] Add schema changes and safe migrations
+- [ ] Establish feature flags/config and baseline telemetry
+
+### Verification
+- [ ] Unit tests for core modules pass
+- [ ] Migrations verified in staging-like environment
+
+## Phase 2 - Feature Implementation
+### Deliverables
+- End-to-end feature behavior
+
+### Tasks
+- [ ] Implement business workflows and process interactions
+- [ ] Implement external/internal interfaces
+- [ ] Add error handling, retry logic, and idempotency protections
+
+### Verification
+- [ ] Integration tests pass
+- [ ] Failure-path behavior verified
+
+## Phase 3 - Hardening and Launch
+### Deliverables
+- Production readiness and release
+
+### Tasks
+- [ ] Add dashboards, alerts, and runbook updates
+- [ ] Execute load/performance and security checks
+- [ ] Run staged rollout and monitor key metrics
+
+### Verification
+- [ ] SLO/SLA criteria met
+- [ ] Rollback procedure validated
+- [ ] Launch sign-off recorded
+```
+
+## Task Authoring Rules
+
+- Write each task as one actionable unit of work.
+- Keep tasks independently checkable.
+- Add explicit verification checkboxes per phase.
+- Do not mark tasks complete unless the user provides completion status.

.codex/skills/feature-architect/references/elixir-architecture.md

@@ -0,0 +1,67 @@
+# Elixir/OTP Architecture Guardrails
+
+Use this reference to keep designs aligned with BEAM strengths.
+
+## 1. System Decomposition
+
+- Organize by domain context, not by transport or framework layer alone.
+- Keep context APIs explicit and stable; avoid leaking persistence concerns.
+- Model long-lived concerns as supervised processes when stateful behavior is required.
+
+## 2. OTP Process Design
+
+- Prefer supervised, isolated processes over shared mutable state.
+- Define restart strategy intentionally (`:one_for_one`, `:rest_for_one`, etc.).
+- Bound process responsibilities; avoid "god" GenServers.
+- Prefer stateless functions unless process state provides clear value.
+
+## 3. Concurrency and Reliability
+
+- Design for message ordering realities and idempotency.
+- Use backpressure-aware patterns for throughput control.
+- Define timeout, retry, and dead-letter behavior explicitly.
+- Prefer `Task.Supervisor` or job systems for controlled async work.
+
+## 4. Persistence and Data Integrity
+
+- Keep transactional boundaries explicit in Ecto contexts.
+- Use database constraints as correctness guarantees, not only app checks.
+- Plan zero-downtime migrations for production paths.
+- Include backfill and rollback strategies for schema evolution.
+
+## 5. Phoenix/Web Layer
+
+- Keep controllers and live views thin; move domain logic into contexts.
+- Validate and normalize inputs at boundaries.
+- Design APIs with explicit contracts and versioning strategy when needed.
+- Use caching and pagination intentionally for read-heavy paths.
+
+## 6. Observability and Operability
+
+- Add Telemetry events for key business and system flows.
+- Define essential metrics: latency, throughput, error rate, saturation.
+- Include structured logs with correlation IDs.
+- Document operational runbooks for failure modes and recovery.
+
+## 7. Security
+
+- Apply least privilege across service and data boundaries.
+- Protect sensitive fields at rest and in transit.
+- Record auditable events for security-relevant actions.
+- Validate authorization decisions in domain-level workflows, not only controllers.
+
+## 8. Testing Expectations
+
+- Unit-test domain rules and pure logic heavily.
+- Integration-test boundary behavior (DB, queues, APIs).
+- Include property tests where invariants matter.
+- Test failure and recovery paths for OTP processes.
+
+## 9. Architecture Decision Quality
+
+For each major choice, document:
+- Decision
+- Alternatives considered
+- Tradeoffs
+- Operational impact
+- Migration and rollback implications

.codex/skills/software-developer/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: software-developer
+description: "Execute senior-level software implementation and bug fixing. Use when Codex should either (1) take feature docs such as `prd.md`, `fdd.md`, and `plan.md` and implement end-to-end, or (2) take an informal bug/issue report, diagnose root cause, propose a targeted fix or fix plan, and proceed with implementation after user confirmation when required."
+---
+
+# Software Developer
+
+Implement production-ready changes with senior engineering rigor, from requirements to verified code.
+
+## Mode Selection
+
+Choose one mode based on input:
+
+1. Feature Implementation Mode
+- Trigger when the user provides feature artifacts (`prd.md`, `fdd.md`, `plan.md`) or asks for end-to-end implementation.
+- Prefer loading these from `docs/features/<feature-slug>/`.
+- Read [references/feature-execution.md](references/feature-execution.md).
+
+2. Bug Fix Mode
+- Trigger when the user provides an issue report, failing behavior, error logs, or regression symptoms.
+- Read [references/bug-fix-playbook.md](references/bug-fix-playbook.md).
+
+## Feature Implementation Mode
+
+1. Build context
+- Parse scope, acceptance criteria, constraints, and phased tasks from provided docs.
+- Trace each planned task to concrete code changes and tests.
+- Surface contradictions or missing requirements early.
+
+2. Execute end-to-end
+- Implement phase-by-phase in the order defined by `plan.md`.
+- Treat each phase as a cohesive set of functionality and complete it before moving to the next phase.
+- If `plan.md` includes PR groups, deliver phases according to that grouping while preserving phase order.
+- Keep changes minimal but complete for each phase.
+- Maintain existing code style and architecture conventions.
+
+3. Validate and close
+- Run relevant tests and linters.
+- Confirm acceptance criteria are met.
+- Update progress tracking checkboxes in `plan.md` for completed tasks and phases.
+- Ensure the final phase (manual QA acceptance testing) is executed and recorded.
+
+## Bug Fix Mode
+
+1. Diagnose first
+- Reproduce the issue when possible.
+- Identify probable root cause and blast radius.
+- Determine whether the fix is low-risk targeted or requires a planned multi-step approach.
+
+2. Choose fix path
+- Targeted fix path: implement immediately when root cause is clear and blast radius is small.
+- Planned fix path: present concise analysis, recommended fix, and risk/validation plan, then request confirmation before editing code.
+
+3. Implement and verify
+- Apply the fix with minimal side effects.
+- Add or update tests that fail before and pass after.
+- Validate affected behavior and adjacent risk areas.
+
+## Delivery Standards
+
+- Explain assumptions and decisions concretely.
+- Prefer root-cause fixes over superficial patches.
+- Keep commits and diffs understandable and scoped.
+- Explicitly call out what was verified and what was not verified.

.codex/skills/software-developer/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Software Developer"
+  short_description: "Implement features or diagnose and fix bugs with senior rigor."
+  default_prompt: "Implement this feature package end-to-end, or analyze this bug and deliver a targeted fix plan and patch."