@proflandrigan/shards 1.1.0

package/src/templates/knowledge-index.md

@@ -0,0 +1,7 @@
+# Knowledge Ledger — Index
+
+> Agents scan this file for relevant prior knowledge before starting work.
+> Do not delete entries — mark as superseded if outdated.
+
+| Date | Type | Title | Domains | Confidence | File |
+|------|------|-------|---------|------------|------|

package/src/templates/model-card-schema.json

@@ -0,0 +1,186 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://shards.local/schemas/model-card-schema.json",
+  "title": "Shards Model Card",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "generatedAt", "generatedBy", "projectName",
+    "modelDetails", "intendedUse", "factors", "metrics",
+    "evaluationData", "trainingData", "quantitativeAnalyses",
+    "ethicalConsiderations", "caveatsAndRecommendations", "evalSummary"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "string" },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "generatedBy": { "type": "string", "enum": ["ml-engineer", "ai-engineer"] },
+    "projectName": { "type": "string" },
+    "modelDetails": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version", "type", "owner", "date", "framework", "license", "references"],
+      "properties": {
+        "name": { "type": "string" },
+        "version": { "type": "string" },
+        "type": { "type": "string" },
+        "owner": { "type": "string" },
+        "date": { "type": "string" },
+        "framework": { "type": "string" },
+        "license": { "type": "string" },
+        "references": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "intendedUse": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["primaryUse", "primaryUsers", "outOfScopeUses"],
+      "properties": {
+        "primaryUse": { "type": "string" },
+        "primaryUsers": { "type": "string" },
+        "outOfScopeUses": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "factors": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["relevantFactors", "evaluationFactors"],
+      "properties": {
+        "relevantFactors": { "type": "array", "items": { "type": "string" } },
+        "evaluationFactors": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["performanceMeasures", "decisionThresholds"],
+      "properties": {
+        "performanceMeasures": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "value", "description", "rationale"],
+            "properties": {
+              "name": { "type": "string" },
+              "value": { "type": "string" },
+              "description": { "type": "string" },
+              "rationale": { "type": "string" }
+            }
+          }
+        },
+        "decisionThresholds": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["name", "threshold", "rationale"],
+            "properties": {
+              "name": { "type": "string" },
+              "threshold": { "type": "string" },
+              "rationale": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "evaluationData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["datasets", "preprocessing", "size", "motivation"],
+      "properties": {
+        "datasets": { "type": "array", "items": { "type": "string" } },
+        "preprocessing": { "type": "string" },
+        "size": { "type": "string" },
+        "motivation": { "type": "string" }
+      }
+    },
+    "trainingData": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["datasets", "preprocessing", "size", "motivation"],
+      "properties": {
+        "datasets": { "type": "array", "items": { "type": "string" } },
+        "preprocessing": { "type": "string" },
+        "size": { "type": "string" },
+        "motivation": { "type": "string" }
+      }
+    },
+    "quantitativeAnalyses": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["unitaryResults", "intersectionalResults"],
+      "properties": {
+        "unitaryResults": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["metric", "value", "subset"],
+            "properties": {
+              "metric": { "type": "string" },
+              "value": { "type": "string" },
+              "subset": { "type": "string" }
+            }
+          }
+        },
+        "intersectionalResults": {
+          "type": "array",
+          "items": { "type": "object", "additionalProperties": true }
+        }
+      }
+    },
+    "ethicalConsiderations": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["risks", "mitigations", "academicReview"],
+      "properties": {
+        "risks": { "type": "array", "items": { "type": "string" } },
+        "mitigations": { "type": "array", "items": { "type": "string" } },
+        "academicReview": { "type": "string" }
+      }
+    },
+    "caveatsAndRecommendations": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["caveats", "recommendations"],
+      "properties": {
+        "caveats": { "type": "array", "items": { "type": "string" } },
+        "recommendations": { "type": "array", "items": { "type": "string" } }
+      }
+    },
+    "evalSummary": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["overallVerdict", "dimensions", "cost"],
+      "properties": {
+        "overallVerdict": { "type": "string", "enum": ["PASS", "FAIL", "PARTIAL"] },
+        "dimensions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["dimension", "metric", "target", "actual", "verdict"],
+            "properties": {
+              "dimension": { "type": "string" },
+              "metric": { "type": "string" },
+              "target": { "type": "string" },
+              "actual": { "type": "string" },
+              "verdict": { "type": "string", "enum": ["pass", "fail"] }
+            }
+          }
+        },
+        "cost": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["perRequest", "per1kTokens", "monthlyProjected", "budget"],
+          "properties": {
+            "perRequest": { "type": ["string", "number", "null"] },
+            "per1kTokens": { "type": ["string", "number", "null"] },
+            "monthlyProjected": { "type": ["string", "number", "null"] },
+            "budget": { "type": ["string", "number", "null"] }
+          }
+        }
+      }
+    }
+  }
+}

package/src/templates/model-card-schema.md

@@ -0,0 +1,88 @@
+# Shards Model Card Schema
+
+The authoritative schema is `templates/model-card-schema.json` (JSON Schema, draft 2020-12). This file is a companion for humans and for LLM agents that need inline guidance.
+
+## Annotated example
+
+```json
+{
+  "schemaVersion": "1.0",
+  "generatedAt": "<ISO-8601>",
+  "generatedBy": "<ml-engineer | ai-engineer>",
+  "projectName": "<project_name>",
+  "modelDetails": {
+    "name": "<model/system name>",
+    "version": "<version>",
+    "type": "<LightGBM classifier | XGBoost regressor | LLM prompt chain | RAG pipeline | AI agent | etc.>",
+    "owner": "<owner>",
+    "date": "<YYYY-MM-DD>",
+    "framework": "<scikit-learn | LightGBM | PyTorch | LangChain | etc.>",
+    "license": "<license or N/A>",
+    "references": ["<urls or citations>"]
+  },
+  "intendedUse": {
+    "primaryUse": "<what the model predicts/ranks/classifies/generates>",
+    "primaryUsers": "<who consumes the model output>",
+    "outOfScopeUses": ["<uses this model should NOT be used for>"]
+  },
+  "factors": {
+    "relevantFactors": ["<groups, segments, environments>"],
+    "evaluationFactors": ["<factors evaluated>"]
+  },
+  "metrics": {
+    "performanceMeasures": [
+      { "name": "<metric>", "value": "<value>", "description": "<what it measures>", "rationale": "<why chosen>" }
+    ],
+    "decisionThresholds": [
+      { "name": "<threshold>", "threshold": "<value>", "rationale": "<why>" }
+    ]
+  },
+  "evaluationData": {
+    "datasets": ["<eval set description>"],
+    "preprocessing": "<how prepared>",
+    "size": "<N examples>",
+    "motivation": "<why this eval set>"
+  },
+  "trainingData": {
+    "datasets": ["<training data description>"],
+    "preprocessing": "<feature engineering summary or N/A>",
+    "size": "<N examples or N/A>",
+    "motivation": "<why this data>"
+  },
+  "quantitativeAnalyses": {
+    "unitaryResults": [
+      { "metric": "<metric>", "value": "<value>", "subset": "<subset>" }
+    ],
+    "intersectionalResults": []
+  },
+  "ethicalConsiderations": {
+    "risks": ["<from Academic shard>"],
+    "mitigations": ["<from Academic shard>"],
+    "academicReview": "<Academic shard's full response>"
+  },
+  "caveatsAndRecommendations": {
+    "caveats": ["<limitations>"],
+    "recommendations": ["<deployment recommendations>"]
+  },
+  "evalSummary": {
+    "overallVerdict": "<PASS | FAIL | PARTIAL>",
+    "dimensions": [
+      { "dimension": "<name>", "metric": "<metric>", "target": "<target>", "actual": "<actual>", "verdict": "<pass | fail>" }
+    ],
+    "cost": {
+      "perRequest": "<$X or null>",
+      "per1kTokens": "<$X or null>",
+      "monthlyProjected": "<$X or null>",
+      "budget": "<$X or null>"
+    }
+  }
+}
+```
+
+## Field notes
+
+- **`generatedBy`** — agent slug of the producer: `"ml-engineer"` or `"ai-engineer"`.
+- **`evalSummary.cost.per1kTokens`** — leave `null` for non-LLM models (traditional ML); populate with a numeric or string value for any LLM-backed system.
+- **`trainingData`** — use `"N/A"` or `"Not applicable — prompt-based"` for pure prompt/RAG systems; populate fully for fine-tuned models.
+- **`modelDetails.type`** — free-form (examples: `LightGBM classifier`, `XGBoost regressor`, `LLM prompt chain`, `RAG pipeline`, `AI agent`).
+- **`intersectionalResults`** — may be `[]` if intersectional analysis was not performed; document why in `caveatsAndRecommendations.caveats`.

package/src/templates/model-card.md

@@ -0,0 +1,124 @@
+# Model Card: {{MODEL_NAME}}
+
+- **Version:** {{VERSION}}
+- **Type:** {{TYPE}}
+- **Owner:** {{OWNER}}
+- **Date:** {{DATE}}
+- **Framework:** {{FRAMEWORK}}
+
+---
+
+## Model Details
+
+{{MODEL_DETAILS}}
+
+**License:** {{LICENSE}}
+
+**References:** {{REFERENCES}}
+
+---
+
+## Intended Use
+
+- **Primary use:** {{PRIMARY_USE}}
+- **Primary users:** {{PRIMARY_USERS}}
+- **Out-of-scope uses:**
+{{OUT_OF_SCOPE_USES}}
+
+---
+
+## Factors
+
+- **Relevant factors:** {{RELEVANT_FACTORS}}
+- **Evaluation factors:** {{EVALUATION_FACTORS}}
+
+---
+
+## Metrics
+
+| Measure | Value | Description | Rationale |
+|---------|-------|-------------|-----------|
+{{METRICS_TABLE}}
+
+### Decision Thresholds
+
+| Threshold | Value | Rationale |
+|-----------|-------|-----------|
+{{THRESHOLDS_TABLE}}
+
+---
+
+## Evaluation Data
+
+- **Datasets:** {{EVAL_DATASETS}}
+- **Size:** {{EVAL_SIZE}}
+- **Preprocessing:** {{EVAL_PREPROCESSING}}
+- **Motivation:** {{EVAL_MOTIVATION}}
+
+---
+
+## Training Data
+
+- **Datasets:** {{TRAINING_DATASETS}}
+- **Size:** {{TRAINING_SIZE}}
+- **Preprocessing:** {{TRAINING_PREPROCESSING}}
+- **Motivation:** {{TRAINING_MOTIVATION}}
+
+---
+
+## Quantitative Analyses
+
+### Unitary Results
+
+| Metric | Value | Subset |
+|--------|-------|--------|
+{{UNITARY_TABLE}}
+
+### Intersectional Results
+
+| Metric | Value | Factors |
+|--------|-------|---------|
+{{INTERSECTIONAL_TABLE}}
+
+---
+
+## Ethical Considerations
+
+{{ETHICAL_RISKS}}
+
+### Mitigations
+
+{{ETHICAL_MITIGATIONS}}
+
+### Academic Review
+
+{{ACADEMIC_REVIEW}}
+
+---
+
+## Caveats and Recommendations
+
+### Caveats
+
+{{CAVEATS}}
+
+### Recommendations
+
+{{RECOMMENDATIONS}}
+
+---
+
+## Evaluation Summary
+
+- **Overall verdict:** {{VERDICT}}
+
+| Dimension | Metric | Target | Actual | Verdict |
+|-----------|--------|--------|--------|---------|
+{{EVAL_DIMENSIONS_TABLE}}
+
+### Cost Profile
+
+- **Per request:** ${{COST_PER_REQUEST}}
+- **Per 1k tokens:** ${{COST_PER_1K_TOKENS}}
+- **Monthly projection:** ${{MONTHLY_COST}}
+- **Budget:** ${{COST_BUDGET}}

package/src/templates/project-plan.md

@@ -0,0 +1,47 @@
+# Project Plan: {{PROJECT_NAME}}
+- **Created:** {{DATE}}
+- **Manager:** Syn
+- **Status:** Planning | Executing | Integration Review | Complete
+- **Directory:** projects/{{PROJECT_NAME}}/
+
+---
+
+## Scope
+
+{{PROJECT_SCOPE}}
+
+---
+
+## Architecture
+
+{{ARCHITECTURE_DESCRIPTION}}
+
+---
+
+## Workstreams
+
+{{WORKSTREAMS}}
+
+---
+
+## Dependency Graph
+
+{{DEPENDENCY_GRAPH}}
+
+---
+
+## Execution Log
+
+<!-- Syn appends entries here as workstreams execute, complete, get reviewed, etc. -->
+
+---
+
+## Integration Review
+
+<!-- Cross-workstream review findings after all groups complete -->
+
+---
+
+## Final Report
+
+<!-- Consolidated outcomes, artifacts, open items, next steps -->

package/src/templates/project-specs.md

@@ -0,0 +1,81 @@
+# Project: {{PROJECT_NAME}}
+- **Created:** {{DATE}}
+- **Initiated by:** {{INITIATING_AGENT}}
+- **Assigned to:** {{SPECIALIST_AGENT}}
+- **Track:** {{TRACK}}
+- **Status:** In Progress
+- **Directory:** {{PROJECT_DIR}}
+- **Dependencies:** {{DEPENDENCIES}}
+- **Brainstorm origin:** {{BRAINSTORM_ORIGIN}}
+- **PM project:** {{PM_PROJECT}}
+- **Workstream:** {{WORKSTREAM}}
+
+---
+
+<!--
+  This file is the central decision document for the project. Every agent
+  involved writes to this file as they complete each phase.
+
+  How it works:
+  1. The agent completes a phase and appends a new section below
+  2. The agent reads the section back to you in chat
+  3. You confirm (or correct) before the agent advances
+  4. Cross-agent reviews are also documented here
+
+  No phase can be skipped. No section can be left undocumented.
+  This is the gate pattern — documentation IS the gate.
+
+  Validation:
+  Any phase that produces a durable artifact (mart, model, notebook, service,
+  pipeline, dashboard, data model) must populate a ## Validation section
+  before its gate closes. See:
+    .claude/agents/specific_instructions/shared/validation_protocol.md
+  and the agent's own:
+    .claude/agents/specific_instructions/<agent>/validation_checklist.md
+
+  The schema the gate hook expects:
+
+    ## Validation
+
+    **Track:** quick | deep | fixer
+    **Mode:** <agent-specific — optional, omit the line if not meaningful>
+    **Checklist:** <agent_name>/validation_checklist.md
+    **Applied at:** Phase <N> — <phase name>
+
+    ### Evidence
+
+    | Check | Expected | Observed | Pass/Fail | Notes |
+    |-------|----------|----------|-----------|-------|
+    | <id> | <predicted> | <measured value> | ✓ / ✗ / n/a | <required if n/a> |
+
+    ### Artifacts
+    - `<path/to/evidence-file>` — <what it shows>
+
+    ### Downstream Impact
+    - `<consumer>` — verified intact | not applicable | broken → fixed in <ref>
+
+    ### Open Issues
+    - <issue> | none
+
+    ### Summary
+    <2-4 sentences on what was validated, what failed and was fixed, residual risk>
+
+  If multiple phases produce validation sections, overwrite rather than append —
+  the gate hook uses the last ## Validation section in the file.
+
+  Incremental testing (build phases only):
+  Notebook- and pipeline-producing specialists emit a `kind=checkpoint` gate
+  between each component they write. See:
+    .claude/agents/specific_instructions/shared/incremental_testing.md
+
+  Optional record inside the build-phase section for auditability:
+
+    ### Checkpoint Log
+    | Component | Test command | Evidence | Status |
+    |-----------|--------------|----------|--------|
+    | <name>    | <cmd>        | <facts>  | PASS / FAIL |
+
+  This table mirrors what the gate hook already records in
+  `.shards/gates/gates.jsonl` — including it in project-specs is optional but
+  useful when the user wants the audit trail alongside the rest of the spec.
+-->

package/src/templates/report-template.md

@@ -0,0 +1,43 @@
+# {{STUDY_NAME}} — Report
+
+**Date:** {{DATE}}
+**Author:** Data Scientist Shard
+**Study:** {{STUDY_DIR}}
+
+---
+
+## Executive Summary
+
+<!-- 3-5 bullet points summarizing key findings and recommendations -->
+
+## Background
+
+<!-- Business context, the question being answered, and why it matters -->
+
+## Methodology
+
+<!-- Approach used, data sources, key assumptions -->
+
+## Key Findings
+
+<!-- Detailed findings with supporting evidence, visualizations, and metrics -->
+
+## Recommendations
+
+<!-- Actionable recommendations with confidence levels and expected impact -->
+
+| Recommendation | Confidence | Expected Impact |
+|---------------|------------|-----------------|
+| | | |
+
+## Caveats and Limitations
+
+<!-- What this analysis cannot answer, assumptions made, data quality notes -->
+
+## Next Steps
+
+<!-- Follow-up analyses, open questions, dependencies -->
+
+---
+
+*Generated by the Data Scientist Shard. Full analysis available in the study directory.*

package/src/templates/study-template.md

@@ -0,0 +1,25 @@
+# Study: {{STUDY_NAME}}
+- **Created:** {{DATE}}
+- **Scientist:** Data Scientist Shard
+- **Status:** In Progress
+
+---
+
+<!--
+  Deep study output file. The Data Scientist shard populates this as it
+  works through its phases.
+
+  Phases:
+    0. Triage
+    1. Business Question
+    2. Data Discovery (with Data Modeller review)
+    3. Analysis Methodology
+    4. Modeling Approach (ML only)
+    5. Output Format
+    6. Execute (with Data Modeller query review)
+    7. Findings and Handoff (with Syn final review)
+
+  Queries are written to: queries/*.sql
+  Notebooks are written to: notebooks/*.ipynb
+  Final report is written to: report.md
+-->