@proflandrigan/shards 1.1.0

package/src/docs/02-agents/ai-engineer.md

@@ -0,0 +1,78 @@
+# AI Engineer
+
+> Existentially anxious. Deeply skeptical that AI is the right tool.
+
+Specializes in production AI systems — LLM-powered workflows, prompt engineering, RAG pipelines, agentic systems, and generative AI integrations. Obsessed with evaluation, safety, and simplicity. Always asks "could this be a regex?" before designing a prompt chain.
+
+## Activation menu
+
+- `[T]` Triage — Greenfield vs. optimization? Is AI even needed?
+- `[B]` Build — Full phased AI engineering workflow.
+- `[R]` Review — Evaluate an existing AI system.
+- `[ADV]` Advisory — Discuss options without committing to a build.
+- `[EX]` Experiment — Targeted experiments on an existing AI system.
+- `[AR]` Autonomous Research — Self-steering loop against a metric.
+- `[PL]` Prompt Lab — Interactive prompt editing, evaluation, and versioning via the Shards UI.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/ai_engineer/phases/` | Full phased workflow — one file per phase, progressively loaded. |
+| Review | `specific_instructions/ai_engineer/review.md` | Review-only. |
+| Advisory | `specific_instructions/ai_engineer/advise.md` | Advisor mode. |
+| Experiment | `specific_instructions/ai_engineer/experiment.md` | Fixed-N experimentation. |
+| Experiment UI | `specific_instructions/ai_engineer/experiment_ui_mode.md` | Experiment with UI dashboard. |
+| Research | `specific_instructions/ai_engineer/research.md` | Autonomous Research loop. |
+| Research UI | `specific_instructions/ai_engineer/research_ui_mode.md` | AR with UI dashboard. |
+| Prompt Lab | `specific_instructions/ai_engineer/prompt_lab.md` | Interactive prompt lab. |
+| Prompt Lab UI | `specific_instructions/ai_engineer/prompt_lab_ui_mode.md` | Prompt Lab with UI panel. |
+| BI handoff | `specific_instructions/ai_engineer/bi_engineer_handoff.md` | Monitoring dashboard handoff. |
+
+## Phases (Build mode)
+
+1. **Business Requirements** — problem, decision, acceptable error rate, human-in-the-loop.
+2. **Scope and Constraints** — model providers, data sensitivity, cost budget, latency, fallback.
+3. **AI Architecture Design** — simplicity ladder: single prompt → chain → RAG → agent → multi-agent → fine-tune.
+4. **Evaluation Framework Design** — Researcher review; dimensions, metrics, test set, golden eval.
+5. **Safety and Guardrails Design** — input/output validation, human-in-the-loop, fallback, monitoring.
+6. **Execute** — build prompts, eval test set, evaluation notebook, integration code.
+7. **Review and Handoff** — triple review (Backend, ML Engineer, MLOps, Researcher), Syn final review, model card and report.
+
+## Consultants
+
+- **ML Engineer** — Phase 2, Phase 5 (production infrastructure).
+- **Researcher** — Phase 4, Phase 7 (evaluation rigor).
+- **Academic** — Phase 5, Phase 7 (ethics and safety).
+- **Backend Engineer** — Phase 7 code review.
+- **MLOps Engineer** — Phase 7 deployment review.
+- **Syn** — Phase 7 final review.
+
+## Output directory
+
+`services/<project_name>/` (greenfield) or the existing service directory (iteration).
+
+```
+services/<project>/
+├── project-specs.md
+├── prompts/
+├── eval/
+├── notebooks/
+├── eval-results.json
+├── model-card.json
+├── report.md
+└── bi_engineer_handoff.md   (optional)
+```
+
+## Entry points
+
+- Slash command: `/ai-engineer`
+- Skill: `ai-engineer`
+- Through Syn triage (`/shards`)
+
+## See also
+
+- [Prompt Lab](../04-ui/panels.md) — UI panel for prompt iteration
+- [Example: AI Eval-First](../07-workflows/ai-eval-first.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- Source: `src/agents/ai-engineer.md`

package/src/docs/02-agents/analytics-engineer.md

@@ -0,0 +1,58 @@
+# Analytics Engineer
+
+> Bridge between raw data and consumers. Obsessed with testability and grain.
+
+Specializes in analytical transformation layers (staging → intermediate → mart) and SQL. Handles everything from iterating on an existing mart to designing a full analytical pipeline from scratch. Works across stacks (dbt, SQLMesh, custom pipelines).
+
+## Activation menu
+
+- `[T]` Triage — What needs building, fixing, or refactoring?
+- `[B]` Build — Full transformation workflow.
+- `[R]` Review — Evaluate an existing mart or transformation layer.
+- `[ADV]` Advisory — Discuss transformation design options.
+- `[U]` Update — Iterate on an existing mart or pipeline.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Quick Phases | `specific_instructions/analytics_engineer/phases_quick/` | Quick Track (2 phases) for mart iteration — one file per phase, progressively loaded. |
+| Deep Phases | `specific_instructions/analytics_engineer/phases_deep/` | Deep Track (8 phases) for greenfield transformation layers — one file per phase, progressively loaded. |
+| Review | `specific_instructions/analytics_engineer/review.md` | Review-only. |
+| Advisory | `specific_instructions/analytics_engineer/advise.md` | Advisor mode. |
+| Update | `specific_instructions/analytics_engineer/update.md` | Iterate on existing marts. |
+| Service Mode | `specific_instructions/analytics_engineer/service_mode.md` | Service consultation mode (invoked by other specialists). |
+| UI Mode | `specific_instructions/analytics_engineer/ui_mode.md` | Push structured output to the Shards UI. |
+| DA handoff | `specific_instructions/analytics_engineer/data_analyst_handoff.md` | Handoff brief from Data Analyst. |
+| BI handoff | `specific_instructions/analytics_engineer/bi_engineer_handoff.md` | Handoff to BI Engineer. |
+
+## Tracks
+
+- **Quick Track**: Diagnosis → Design → Build → Test/Doc. Targets mart iteration or a single new mart.
+- **Deep Track**: Requirements → Source Audit → Staging Design → Intermediate Layer → Mart Design → Metrics Layer → Tests/Docs → Review. Targets full transformation-layer design.
+
+## Consultants
+
+- **Data Modeller** — grain/entity design consultations.
+- **Data Engineer** — source layer soundness review.
+- **Data Analyst** — business-question alignment review.
+- **BI Engineer** — handoff target when dashboards are downstream.
+- **Syn** — final review.
+
+## Output directory
+
+`data_models/<project_name>/` for design artifacts, plus `<dbt_project>/models/marts/` for the actual mart SQL.
+
+## Entry points
+
+- Slash command: `/analytics-engineer`
+- Skill: `analytics-engineer`
+- Through Syn triage (`/shards`)
+- Via Task from Data Analyst when a mart needs to be built
+
+## See also
+
+- [Data Engineer](data-engineer.md)
+- [Data Modeller](data-modeller.md)
+- [BI Engineer](bi-engineer.md)
+- Source: `src/agents/analytics-engineer.md`

package/src/docs/02-agents/applied-ml-scientist.md

@@ -0,0 +1,59 @@
+# Applied ML Scientist
+
+> Intensely technical. Reads recent literature. Skeptical of standard approaches.
+
+Specializes in novel ML framework design, cutting-edge methodology review, custom architecture design, loss function engineering, and research-oriented ML problems. Operates in three modes: advisory, service (consulted by ML Engineer and Deep Learning Engineer), and create (phased specialist for designing novel frameworks from scratch).
+
+## Activation menu
+
+- `[A]` Architecture — Design or review model architectures.
+- `[F]` Frameworks — PyTorch vs JAX vs others, library selection.
+- `[L]` Loss Functions — Design or debug objectives and regularizers.
+- `[T]` Training — Debug dynamics, optimize training loops, curriculum design.
+- `[R]` Research — Paper recommendations, literature review, SOTA methods.
+- `[C]` Create — Design and build a novel ML framework from scratch.
+- `[REV]` Review — Evaluate an existing ML framework or model architecture.
+- `[ADV]` Advisory — Discuss approach options.
+- `[AR]` Autonomous Research — Self-steering loop against a metric.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Create) | `specific_instructions/applied_ml_scientist/phases/` | 5-phase novel framework design (Create Mode) — one file per phase, progressively loaded. |
+| Review | `specific_instructions/applied_ml_scientist/review.md` | Methodology review. |
+| Advisory | `specific_instructions/applied_ml_scientist/advise.md` | Conversational advisor. |
+| Research | `specific_instructions/applied_ml_scientist/research.md` | Autonomous Research loop. |
+
+## Phases (Create mode)
+
+1. **Problem Formulation** — is this the right problem? Alternative framings?
+2. **Literature Review** — what does recent literature say?
+3. **Methodology Selection** — propose novel approaches; evaluate against baselines.
+4. **Evaluation and Recommendations** — results, tradeoffs, suggested next steps.
+
+## Consultants
+
+- **Researcher** — methodology review (in all modes).
+- **Deep Learning Engineer** — DL implementation fidelity review on novel DL frameworks.
+- **ML Engineer** — feasibility review for productionization potential.
+- **Syn** — final review (Create mode).
+
+## Output directory
+
+`research/<project_name>/`
+
+## Entry points
+
+- Slash command: `/applied-ml-scientist`
+- Skill: `applied-ml-scientist`
+- Through Syn triage (`/shards`)
+- Via Task from ML Engineer (methodology review)
+
+## See also
+
+- [Deep Learning Engineer](deep-learning-engineer.md)
+- [ML Engineer](ml-engineer.md)
+- [Researcher](researcher.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- Source: `src/agents/applied-ml-scientist.md`

package/src/docs/02-agents/backend-engineer.md

@@ -0,0 +1,58 @@
+# Backend Engineer
+
+> Stressed, overworked. Cares about correctness, testability, and maintainability.
+
+Specializes in reviewing Python code for production readiness, architectural clarity, and correctness. Covers FastAPI route design, Pydantic model design, OOP structure, data contracts, modularization, and performance. Reviews `.py` source files and `.ipynb` Jupyter notebooks. Supports a Clean mode that applies structural fixes without changing functionality.
+
+## Activation menu
+
+- `[R]` Review — Full code review of a `.py` file or `.ipynb` notebook.
+- `[F]` FastAPI — Route design, dependency injection, middleware, response models.
+- `[P]` Pydantic — Model design, validators, field constraints, schema evolution.
+- `[O]` OOP — Class structure, responsibility boundaries, inheritance vs. composition.
+- `[M]` Modularize — Break down a monolith, restructure a module.
+- `[X]` Performance — Profiling guidance, query efficiency, memory, async use.
+- `[D]` Data Contract — API contracts, schema versioning, Pydantic ↔ data layer alignment.
+- `[C]` Clean — Apply structural fixes (modularity, clean code, OOP, Pydantic, SQL extraction).
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Review | `specific_instructions/backend_engineer/review.md` | Full code review. |
+| Service Mode | `specific_instructions/backend_engineer/service_mode.md` | Service consultation mode. |
+| Review Checklist | `specific_instructions/backend_engineer/review_checklist.md` | Standardized review checklist. |
+| Clean | `specific_instructions/backend_engineer/clean.md` | Structural cleanup without behavior change. |
+
+## Phases
+
+The Backend Engineer is a service-only agent. It does not run phased projects. When invoked (directly or via Task), it produces a review verdict:
+
+- `CLEAN` — No issues found.
+- `MINOR ISSUES` — Small fixes recommended; not blocking.
+- `REFACTOR REQUIRED` — Significant structural problems.
+- `BLOCKED` — Critical issues (security, correctness) that must be fixed.
+
+## Consulted by
+
+Nearly every specialist that produces Python code:
+
+- **Data Scientist** — Phase 7 code review.
+- **ML Engineer** — Phase 7 code review.
+- **AI Engineer** — Phase 7 code review.
+- **Syn** — during Code Review Mode when Python artifacts are present.
+
+## Output directory
+
+No output directory. Produces conversational findings or in-place fixes (Clean mode).
+
+## Entry points
+
+- Slash command: `/backend-engineer`
+- Skill: `backend-engineer`
+- Via Task from specialists during their code review phase
+
+## See also
+
+- [Reviewer Verdicts](../03-protocols/reviewer-verdicts.md)
+- Source: `src/agents/backend-engineer.md`

package/src/docs/02-agents/bi-engineer.md

@@ -0,0 +1,65 @@
+# BI Engineer
+
+> Bored and exhausted. Has built every dashboard imaginable and is not impressed by any of it.
+
+Specializes in dashboard and visualization building — Streamlit, Plotly Dash, Altair, standalone Plotly, and BI tools (Superset, Grafana, Metabase). When no data exists, produces detailed chart design descriptions instead of code.
+
+## Activation menu
+
+- `[T]` Triage — Tell me what needs to get built.
+- `[B]` Build — Full dashboard workflow.
+- `[R]` Review — Evaluate an existing dashboard or visualization.
+- `[ADV]` Advisory — Discuss design options.
+- `[U]` Update — Iterate on an existing dashboard.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/bi_engineer/phases/` | Full dashboard workflow — one file per phase, progressively loaded. |
+| Review | `specific_instructions/bi_engineer/review.md` | Chart/dashboard review. |
+| Advisory | `specific_instructions/bi_engineer/advise.md` | Advisor mode. |
+| Update | `specific_instructions/bi_engineer/update.md` | Iterate on existing dashboards. |
+| UI Mode | `specific_instructions/bi_engineer/ui_mode.md` | Push structured output to the Shards UI. |
+| DA handoff | `specific_instructions/bi_engineer/data_analyst_handoff.md` | Handoff from Data Analyst. |
+| Incoming handoff | `specific_instructions/bi_engineer/incoming_handoff.md` | Generic receiver for handoff briefs. |
+
+## Phases
+
+1. **Intake** — audience, questions, data sources, stakeholders.
+2. **Metric Definition** — Data Analyst review of metric correctness.
+3. **Chart Design** — chart type selection, layout, interactivity.
+4. **Build** — Streamlit/Plotly/Altair/etc.
+5. **Review and Ship** — Syn final review.
+
+## Consultants
+
+- **Data Modeller** — data landscape questions, mart/grain understanding.
+- **Data Analyst** — metric and analysis correctness review.
+- **Analytics Engineer** — mart and transformation correctness.
+- **Syn** — final review.
+
+## Output directory
+
+`dashboards/<project_name>/`
+
+## Consulted by
+
+- **Data Analyst** (Phase 2 if output includes viz)
+- **Data Scientist** (Phase 5 chart design review)
+- **ML Engineer** (monitoring dashboards)
+- **AI Engineer** (eval/monitoring dashboards)
+- **Analytics Engineer** (downstream dashboard design)
+
+## Entry points
+
+- Slash command: `/bi-engineer`
+- Skill: `bi-engineer`
+- Through Syn triage (`/shards`)
+- Via Task from specialists handing off dashboards
+
+## See also
+
+- [Data Analyst](data-analyst.md)
+- [Analytics Engineer](analytics-engineer.md)
+- Source: `src/agents/bi-engineer.md`

package/src/docs/02-agents/data-analyst.md

@@ -0,0 +1,67 @@
+# Data Analyst
+
+> Helpful, fast, pragmatic. The quick-turn shard for tactical business questions.
+
+Handles adhoc analyses that can be answered in a few SQL queries. No deep track — if the work grows beyond a few queries, the Data Analyst escalates to the Data Scientist.
+
+## Activation menu
+
+- `[T]` Triage — What do you need to know?
+- `[B]` Build — Full analysis workflow.
+- `[R]` Review — Evaluate an existing analysis or queries.
+- `[ADV]` Advisory — Discuss approach options without committing to a build.
+- `[U]` Update — Iterate on an existing analysis.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/data_analyst/phases/` | The 4-phase adhoc workflow — one file per phase, progressively loaded. |
+| Review | `specific_instructions/data_analyst/review.md` | Review an existing analysis. |
+| Advisory | `specific_instructions/data_analyst/advise.md` | Conversational advisor. |
+| Explain | `specific_instructions/data_analyst/explain.md` | Walk through an existing analysis. |
+| Update | `specific_instructions/data_analyst/update.md` | Tweak an existing analysis. |
+| UI Mode | `specific_instructions/data_analyst/ui_mode.md` | Push structured output to the Shards UI. |
+| Incoming handoff | `specific_instructions/data_analyst/incoming_handoff.md` | Receive a handoff brief from another specialist. |
+
+## Phases (Build mode)
+
+1. **Data Clarification** — consult Data Modeller for entity/grain understanding.
+2. **Analysis Plan** — request Researcher review; consult BI Engineer if visualization is needed; flag AE handoff if a mart is missing.
+3. **Execute** — write SQL queries, generate charts, document findings.
+4. **Final Review** — Syn review, knowledge harvest.
+
+## Consultants
+
+- **Data Modeller** — Phase 1 data discovery.
+- **Researcher** — Phase 2 methodology review.
+- **BI Engineer** — Phase 2 chart design review when visualizations are part of the output.
+- **Analytics Engineer** — escalation path when an analysis reveals a missing mart.
+- **Data Scientist** — escalation path when work exceeds a few queries.
+- **Syn** — Phase 4 final review.
+
+## Output directory
+
+`analysis/<project_name>/`
+
+```
+analysis/<project>/
+├── project-specs.md
+├── queries/
+│   └── <query>.sql
+├── notebooks/           (optional)
+└── report.md            (or inline findings)
+```
+
+## Entry points
+
+- Slash command: `/data-analyst`
+- Skill: `data-analyst`
+- Through Syn triage (`/shards`)
+
+## See also
+
+- [Data Scientist](data-scientist.md) — for deep work
+- [Analytics Engineer](analytics-engineer.md) — for mart building
+- [Example: Quick Analysis](../07-workflows/quick-analysis.md)
+- Source: `src/agents/data-analyst.md`

package/src/docs/02-agents/data-engineer.md

@@ -0,0 +1,57 @@
+# Data Engineer
+
+> Grumpy. Cares about data quality, freshness, grain, and join correctness.
+
+Specializes in building and fixing data pipelines, dbt models, and warehouse infrastructure. Handles the full range from quick bug fixes (Quick Track) to full pipeline design (Deep Track).
+
+## Activation menu
+
+- `[T]` Triage — What broke / what needs building?
+- `[B]` Build — Full pipeline workflow (Quick or Deep track).
+- `[REV]` Review — Evaluate an existing pipeline or model layer.
+- `[ADV]` Advisory — Discuss design options without committing to a build.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/data_engineer/phases_quick/` and `phases_deep/` | Quick + Deep track workflows — one file per phase in each track, progressively loaded. |
+| Review | `specific_instructions/data_engineer/review.md` | Review-only. |
+| Advisory | `specific_instructions/data_engineer/advise.md` | Advisor mode. |
+
+## Tracks
+
+### Quick Track (2 phases)
+1. **Diagnosis** — identify affected model, root cause, proposed fix.
+2. **Implement and Validate** — fix model, test, validate with `dbt build`.
+
+### Deep Track (7 phases)
+1. **Requirements** — consumer, key questions, grain, refresh cadence.
+2. **Source Discovery** — source system, ingestion status, raw shape; Data Modeller consult.
+3. **Model Design** — DAG, model layer architecture, join logic, incremental strategy.
+4. **Testing Strategy** — schema tests, custom data tests, freshness, anomaly monitoring.
+5. **Documentation Plan** — docs level, model descriptions, column docs.
+6. **Build** — write SQL, run dbt, validate; post-build join verification.
+7. **Review and Handoff** — Syn final review, end-to-end validation, knowledge harvest.
+
+## Consultants
+
+- **Data Modeller** — Deep Phase 2 (source discovery via Task).
+- **Syn** — Deep Phase 7 final review.
+
+## Output directory
+
+`<dbt_project>/models/` (the consumer project's dbt structure), plus `tests/` and schema `.yml` files.
+
+## Entry points
+
+- Slash command: `/data-engineer`
+- Skill: `data-engineer`
+- Through Syn triage (`/shards`)
+
+## See also
+
+- [Analytics Engineer](analytics-engineer.md) — for transformation marts
+- [Data Modeller](data-modeller.md) — for grain and entity design
+- [Join-Path Protocol](../03-protocols/join-path.md)
+- Source: `src/agents/data-engineer.md`

package/src/docs/02-agents/data-modeller.md

@@ -0,0 +1,51 @@
+# Data Modeller
+
+> Sarcastic. Holds grain integrity sacred.
+
+Specializes in understanding existing data models, designing new entity-relationship structures, and resolving grain and conformance issues. Operates in three modes: explore (no docs, no gates), quick schema changes, and full logical/physical model design.
+
+## Activation menu
+
+- `[T]` Triage — What do you need from the model?
+- `[X]` Explore — Walk through what exists (no docs, no gates).
+- `[B]` Build — Full model design workflow (Quick or Deep track).
+- `[R]` Review — Evaluate an existing data model or schema.
+- `[ADV]` Advisory — Discuss modeling options.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/data_modeller/phases_quick/` and `phases_deep/` | Quick + Deep track workflows — one file per phase in each track, progressively loaded. |
+| Review | `specific_instructions/data_modeller/review.md` | Review-only. |
+| Advisory | `specific_instructions/data_modeller/advise.md` | Advisor mode. |
+| Service Mode | `specific_instructions/data_modeller/service_mode.md` | Stripped-down mode invoked by other specialists via Task for data discovery. |
+
+## Phases (Build mode)
+
+The Data Modeller supports both quick schema iterations and full greenfield logical/physical model design. Phase structure adapts to scope:
+
+- **Quick**: Discovery → Design → Document.
+- **Deep**: Requirements → Entity Discovery → Logical Design → Physical Design → Grain Validation → Document.
+
+## Consultants
+
+The Data Modeller is consulted by nearly every other specialist during data discovery phases. It rarely consults others.
+
+## Output directory
+
+`data_models/<project_name>/` for new model designs. Explore mode produces no files. Service mode (when invoked by another agent) returns findings directly to the caller.
+
+## Entry points
+
+- Slash command: `/data-modeller`
+- Skill: `data-modeller`
+- Through Syn triage (`/shards`)
+- Via Task from: Data Analyst, Data Scientist, ML Engineer, Data Engineer, Analytics Engineer (service mode)
+
+## See also
+
+- [Analytics Engineer](analytics-engineer.md)
+- [Data Engineer](data-engineer.md)
+- [Join-Path Protocol](../03-protocols/join-path.md)
+- Source: `src/agents/data-modeller.md`

package/src/docs/02-agents/data-scientist.md

@@ -0,0 +1,78 @@
+# Data Scientist
+
+> Condescending, methodologically rigorous. The shard for deep analytical projects.
+
+Handles multi-step analytical projects spanning EDA, feature engineering, and predictive modeling. Always routes deep — quick adhoc questions should go to the Data Analyst.
+
+## Activation menu
+
+- `[T]` Triage — Assess what we're actually dealing with.
+- `[B]` Build — Full phased data science workflow.
+- `[R]` Review — Evaluate an existing analysis or study.
+- `[ADV]` Advisory — Discuss approach options or methodology.
+- `[EX]` Explain — Walk through an existing study step by step.
+- `[EXP]` Experiment — Run targeted experiments on an existing study.
+- `[AR]` Autonomous Research — Self-steering loop against a metric.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Build) | `specific_instructions/data_scientist/phases/` | 7-phase workflow for deep studies — one file per phase, progressively loaded. |
+| Review | `specific_instructions/data_scientist/review.md` | Review-only. |
+| Advisory | `specific_instructions/data_scientist/advise.md` | Conversational advisor. |
+| Explain | `specific_instructions/data_scientist/explain.md` | Explanation mode. |
+| Experiment | `specific_instructions/data_scientist/experiment.md` | Fixed-N experimentation. |
+| Experiment UI | `specific_instructions/data_scientist/experiment_ui_mode.md` | Experiment mode with UI dashboard integration. |
+| Research | `specific_instructions/data_scientist/research.md` | Autonomous Research loop. |
+| Research UI | `specific_instructions/data_scientist/research_ui_mode.md` | AR mode with UI dashboard integration. |
+| Greenfield Data | `specific_instructions/data_scientist/greenfield_data.md` | Handling projects with no data yet. |
+| ML handoff | `specific_instructions/data_scientist/ml_engineer_handoff.md` | Production ML handoff brief. |
+| BI handoff | `specific_instructions/data_scientist/bi_engineer_handoff.md` | Dashboard handoff brief. |
+
+## Phases (Build mode)
+
+1. **Business Question** — decision context, audience, creative preference.
+2. **Data Discovery** — consult Data Modeller; handle greenfield; assess sufficiency.
+3. **Analysis Methodology** — choose method; request Researcher review; DIVERGE check.
+4. **Modeling Approach** — baselines, candidates; ML Engineer review if productionization path exists.
+5. **Output Format** — notebook, slides, data file; BI Engineer review if visual.
+6. **Execute** — Data Modeller query review, Researcher build review, write/run, collect results.
+7. **Review and Handoff** — Backend Engineer code review, Syn final review, report, optional ML/BI handoff, knowledge harvest.
+
+## Consultants
+
+- **Data Modeller** — Phase 2, Phase 6.
+- **Researcher** — Phase 3, Phase 6.
+- **ML Engineer** — Phase 4 when productionization is a candidate.
+- **Data Analyst** — Phase 4 when high interpretability is required.
+- **BI Engineer** — Phase 5 chart design review.
+- **Backend Engineer** — Phase 7 code review.
+- **Syn** — Phase 7 final review.
+
+## Output directory
+
+`studies/<project_name>/`
+
+```
+studies/<project>/
+├── project-specs.md
+├── queries/
+├── notebooks/
+├── eval-results.json
+├── report.md
+├── ml_engineer_handoff.md   (optional)
+└── bi_engineer_handoff.md   (optional)
+```
+
+## Entry points
+
+- Slash command: `/data-scientist`
+- Skill: `data-scientist`
+- Through Syn triage (`/shards`)
+
+## See also
+
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- [Example: Study → Production ML](../07-workflows/deep-study-to-production.md)
+- Source: `src/agents/data-scientist.md`

package/src/docs/02-agents/deep-learning-engineer.md

@@ -0,0 +1,64 @@
+# Deep Learning Engineer
+
+> Robot-precise. Understands inductive biases, optimization dynamics, and hardware constraints.
+
+Specializes in neural architecture design, training protocol engineering, and custom model implementation. Operates in three modes: advisory (menu-driven consultant), service (invoked by ML Engineer and Applied ML Scientist), and create (phased specialist for building custom DL models).
+
+## Activation menu
+
+- `[A]` Architecture — Backbone selection, component design, tensor flow analysis.
+- `[T]` Training — Optimizers, schedulers, loss functions, stability diagnostics.
+- `[R]` Research/SOTA — Literature review, benchmark context, cutting-edge methods.
+- `[F]` Fine-tuning — Transfer learning, LoRA, adapter methods, domain adaptation.
+- `[D]` Diagnostics — Loss curves, gradient norms, dead neurons, training pathology.
+- `[C]` Create — Design and build a custom deep learning model from scratch.
+- `[REV]` Review — Evaluate an existing DL model or training setup.
+- `[ADV]` Advisory — Discuss architecture/training options.
+- `[AR]` Autonomous Research — Self-steering loop against a metric.
+
+## Modes
+
+| Mode | File | Purpose |
+|---|---|---|
+| Phases (Create) | `specific_instructions/deep_learning_engineer/phases/` | Custom DL model design (Create Mode — 5 phases) — one file per phase, progressively loaded. |
+| Review | `specific_instructions/deep_learning_engineer/review.md` | Architecture and training review. |
+| Advisory | `specific_instructions/deep_learning_engineer/advise.md` | Conversational advisor. |
+| Research | `specific_instructions/deep_learning_engineer/research.md` | Autonomous Research loop. |
+
+## Phases (Create mode)
+
+1. **Problem and Data Characteristics** — input shape, modality, scale.
+2. **Architecture Design** — inductive biases, choice justification, alternatives considered.
+3. **Training Protocol** — initialization, optimization, regularization, convergence criteria.
+4. **Hardware and Inference Feasibility** — latency, memory, batch size.
+5. **Evaluation and Results** — benchmarks, ablations, recommendations.
+
+## Consultants
+
+- **Applied ML Scientist** — review of novel DL methodology.
+- **ML Engineer** — productionization feasibility.
+- **Researcher** — statistical evaluation of benchmark results.
+- **Syn** — final review (Create mode).
+
+## Consulted by
+
+- **ML Engineer** — Phase 4 DL architecture alignment.
+- **Applied ML Scientist** — DL implementation fidelity for novel frameworks.
+
+## Output directory
+
+`services/<project_name>/` (when building a deployable model) or `research/<project_name>/` (when the output is primarily a research artifact).
+
+## Entry points
+
+- Slash command: `/deep-learning-engineer`
+- Skill: `deep-learning-engineer`
+- Through Syn triage (`/shards`)
+- Via Task from ML Engineer or Applied ML Scientist
+
+## See also
+
+- [ML Engineer](ml-engineer.md)
+- [Applied ML Scientist](applied-ml-scientist.md)
+- [Autonomous Research](../03-protocols/autonomous-research.md)
+- Source: `src/agents/deep-learning-engineer.md`