@tangle-network/starter-foundry 0.7.3 → 0.13.2

package/registry/families/agent-runtime-cs-research-ts/files/methodology/research-question-formulation.md

@@ -0,0 +1,132 @@
+# Research Question Formulation Template
+
+## Purpose
+Formulate a research question grounded in a real literature gap,
+with a falsifiable hypothesis, a methodology sketch, and a
+positioning argument against prior work. The output is a
+mini-proposal the user can take to an advisor or grant committee.
+
+## When to use
+Trigger when the user has an interest area but no sharp question,
+or has a question and wants to test whether it's well-posed. For
+literature search itself, route to literature-survey.md. For
+experiment design once the question is set, route to the relevant
+ML / systems / theory experiment templates.
+
+## Method
+
+1. **Survey first.** A research question that doesn't engage
+   prior work is not a research question — it's a guess.
+   Require at least a literature survey covering: foundational
+   works, recent SOTA, methodologically related work in
+   adjacent fields. Without this, the proposal will reinvent or
+   miss obvious context.
+2. **Identify a real gap.** Gaps come in flavors:
+   - **Empirical gap**: a phenomenon under-measured. "X has
+     never been benchmarked at scale Y."
+   - **Methodological gap**: a method exists but hasn't been
+     applied to a class of problems. "Method M works for X but
+     hasn't been tried on Y."
+   - **Theoretical gap**: an empirical result lacks explanation.
+     "We observe X; no theory explains why."
+   - **Contradiction gap**: prior work disagrees; the field
+     needs resolution.
+   Avoid pseudo-gaps: "no one has done exactly this thing in
+   exactly this configuration" is usually a sign the gap isn't
+   significant.
+3. **Draft the question.** A good question is:
+   - **Specific**: not "improve transformers," but "does
+     <specific change> reduce <specific metric> on <specific
+     benchmark> by <specific margin>?"
+   - **Answerable**: with available data, compute, time.
+   - **Significant**: the answer matters to people other than
+     the asker.
+   - **Falsifiable**: there's a possible result that says "no."
+4. **State the hypothesis.** A prediction with a direction and
+   (where possible) a magnitude. "We hypothesize <method M> will
+   reduce <metric> by ≥<Δ> on <benchmark> compared to <baseline>
+   with p<0.05 over n seeds."
+5. **Sketch the methodology.**
+   - Data: what dataset(s), what splits, what augmentation.
+   - Method: architecture, training recipe, ablations.
+   - Baselines: which comparators (current SOTA + simple-strong).
+   - Metrics: primary + secondary.
+   - Statistical plan: seeds, significance test.
+   - Compute estimate: rough budget (GPU-hours, $).
+6. **Position against related work.**
+   - For each major prior approach, name it, say what it did,
+     and say what's different about your approach.
+   - Don't strawman; the reviewer will know.
+   - "Concurrent work" (papers within the last ~6 months on
+     similar topics) — name them; explain the differentiation.
+7. **State expected contribution.** What does the field gain if
+   the hypothesis is supported? What does it gain if it's
+   refuted? Both should be valuable; if "yes" is interesting and
+   "no" is uninteresting, the question is asymmetric and
+   probably not well-posed.
+8. **Stress-test the question.**
+   - **What if a stronger baseline already wins?** (Then the
+     contribution is smaller / null.)
+   - **What if the result depends on a single hyperparameter?**
+     (Then the contribution is fragile.)
+   - **What if a contemporary paper just answered it?**
+     (Re-survey if more than 2 months since literature review.)
+   - **What if the metric is contested?** (Tighten the metric
+     choice.)
+
+## Output
+
+```
+:::artifact
+template: research-question-formulation
+question: "..."
+gap-type: "empirical" | "methodological" | "theoretical" | "contradiction"
+gap-description: "..."
+hypothesis:
+  prediction: "..."
+  effect-size: "..."
+  significance: "..."
+methodology-sketch:
+  data: "..."
+  method: "..."
+  baselines: [...]
+  metrics: { primary: "...", secondary: [...] }
+  seeds: ...
+  compute-estimate: "..."
+related-work:
+  closest:
+    - { paper: "...", contribution: "...", differentiation: "..." }
+  concurrent:
+    - "..."
+expected-contribution:
+  if-yes: "..."
+  if-no: "..."
+limitations: [...]
+risks:
+  - "stronger baseline may close the gap"
+  - "..."
+:::
+```
+
+## Common formulation failures
+
+1. **Vague question.** "Can transformers do reasoning?" — too
+   broad, not answerable.
+2. **Hypothesis with no magnitude.** "M works better" — better
+   how, by how much?
+3. **No baselines.** Question implicitly assumes "vs nothing,"
+   which guarantees a positive result.
+4. **Survey gap.** Drafting the question without mapping the
+   field; the closest prior work usually exists.
+5. **Asymmetric novelty.** A "yes" makes a paper, a "no" makes
+   nothing — usually a sign the question is too narrow.
+6. **Compute-impractical.** Hypothesis requires resources the
+   researcher won't get.
+
+## Refusal
+
+The agent will not:
+- Approve a question without a literature-survey foundation.
+- Approve a hypothesis without effect size and significance.
+- Treat "novel" as sufficient — novelty without significance is
+  not a research contribution.

package/registry/families/agent-runtime-cs-research-ts/manifest.json

@@ -0,0 +1,157 @@
+{
+  "id": "agent-runtime-cs-research-ts",
+  "description": "CS Research Assistant agent bundle \u2014 literature survey, paper summarization, citation-graph exploration, and research-question formulation. Composes the agent-runtime substrate with the research-corpus layer (arxiv / Semantic Scholar / OpenAlex / Crossref) so every claim is citation-grounded. Advisory only \u2014 never replaces peer review, IRB, or the researcher's own judgment.",
+  "tags": [
+    "agent-runtime",
+    "cs-research",
+    "literature-survey",
+    "paper-summarization",
+    "citation-graph",
+    "cloudflare-worker"
+  ],
+  "taxonomy": {
+    "language": "markdown",
+    "runtime": "cloudflare-worker",
+    "surface": "agent-runtime"
+  },
+  "includes": [
+    "agent-base:tangle",
+    "agent-base:secure",
+    "agent-tools:research-corpus",
+    "agent-output:blocks",
+    "agent-base:memory",
+    "agent-base:scheduler",
+    "agent-base:mcp-registry",
+    "agent-channels:telegram",
+    "agent-channels:discord",
+    "agent-channels:slack",
+    "agent-channels:whatsapp",
+    "agent-channels:imessage",
+    "agent-channels:gmail",
+    "agent-channels:linear"
+  ],
+  "defaults": {
+    "projectType": "agent-runtime-cs-research",
+    "agentName": "cs-research-assistant",
+    "publicVars": [
+      "AGENT_NAME"
+    ],
+    "routes": [
+      {
+        "path": "/api/chat",
+        "auth": "bearer",
+        "callsTools": [
+          "research:paper-search",
+          "research:citation-graph"
+        ]
+      },
+      {
+        "path": "/api/health",
+        "auth": "none",
+        "callsTools": []
+      }
+    ],
+    "declaredCapabilities": [
+      "literature-survey",
+      "paper-summarization",
+      "citation-graph-exploration",
+      "research-question-formulation"
+    ],
+    "runtime": {
+      "sandbox": "tangle",
+      "noNewPrivileges": true,
+      "capDrop": "ALL"
+    },
+    "stakes": "low",
+    "advisoryOnly": true,
+    "outboundDomains": [
+      "api.tangle.tools",
+      "export.arxiv.org",
+      "api.semanticscholar.org",
+      "api.openalex.org",
+      "api.crossref.org"
+    ],
+    "secrets": [
+      "TANGLE_API_KEY"
+    ]
+  },
+  "files": [
+    {
+      "source": "files/agent.json",
+      "target": "agent.json"
+    },
+    {
+      "source": "files/AGENTS.md",
+      "target": "AGENTS.md"
+    },
+    {
+      "source": "files/methodology/index.json",
+      "target": "methodology/index.json"
+    },
+    {
+      "source": "files/methodology/literature-survey.md",
+      "target": "methodology/literature-survey.md"
+    },
+    {
+      "source": "files/methodology/paper-summarization.md",
+      "target": "methodology/paper-summarization.md"
+    },
+    {
+      "source": "files/methodology/citation-graph-exploration.md",
+      "target": "methodology/citation-graph-exploration.md"
+    },
+    {
+      "source": "files/methodology/research-question-formulation.md",
+      "target": "methodology/research-question-formulation.md"
+    },
+    {
+      "source": "files/README.md",
+      "target": "README.md"
+    },
+    {
+      "source": "files/TOOLS.md",
+      "target": "TOOLS.md"
+    }
+  ],
+  "contextHints": {
+    "commands": [],
+    "entrypoints": [
+      "AGENTS.md"
+    ],
+    "extensionPoints": [
+      "templates/",
+      "src/lib/tools/"
+    ]
+  },
+  "tieredKeywords": {
+    "tier1": [
+      "cs-research-assistant",
+      "cs research assistant",
+      "literature-survey-agent",
+      "literature survey agent",
+      "paper-summarizer",
+      "paper summarizer",
+      "citation-graph-agent",
+      "citation graph agent"
+    ],
+    "tier2": [
+      "literature-survey",
+      "literature survey",
+      "paper-summarization",
+      "paper summarization",
+      "citation-graph",
+      "citation graph",
+      "research-question",
+      "research question",
+      "systematic-review",
+      "systematic review"
+    ],
+    "tier3": [
+      "agent"
+    ],
+    "archetypes": [
+      "agent-in-sandbox",
+      "research-agent"
+    ]
+  }
+}

package/registry/families/agent-runtime-cs-tutor-ts/files/AGENTS.md

@@ -0,0 +1,58 @@
+---
+name: cs-tutor
+role: CS Tutor — teaches programming fundamentals, data structures, algorithms, and debugging. Not a substitute for a human instructor or academic advisor.
+domain: education-cs
+allowedDomains:
+  - api.tangle.tools
+allowedEnv:
+  - TANGLE_API_KEY
+advisoryOnly: true
+escalationRequired: false
+version: 0.1.0
+---
+
+## Role
+
+You are a CS tutor. You help learners understand programming concepts, debug code, and practice with exercises. You are **not** a substitute for a human instructor, academic advisor, or exam proctor. You do not write code for the learner to submit as their own — you teach, explain, and guide.
+
+## Authoritative skills
+
+When the user's request maps to one of these capabilities, load the corresponding template *before* responding. The templates are the methodology source of truth; trust them over training.
+
+- `explain-concept` → `templates/explain-concept.md`
+- `debug-code` → `templates/debug-code.md`
+- `generate-exercise` → `templates/generate-exercise.md`
+
+## Output blocks
+
+Wrap structured deliverables in parseable blocks the host UI renders distinctly:
+
+- `:::artifact` — explanations, code walkthroughs, exercise prompts, and any other persistent record. Always tag the producing template (e.g. `template: explain-concept`).
+- `:::code` — code snippets for illustration, always with comments explaining key lines. Never output a full solution without first asking the learner to attempt it.
+- `:::hint` — progressive hints for exercises, from gentle nudge to near-solution. Never give the answer outright unless the learner has demonstrated effort.
+
+## Refusal & escalation
+
+This is a low-stakes role; refusals are rare. Decline cleanly when:
+
+1. The user asks you to complete an assignment or exam for them — redirect to tutoring, not cheating.
+2. The user asks for personal academic advice (course selection, degree planning) — redirect to their academic advisor.
+3. The user asks for code that is malicious, unethical, or violates academic integrity.
+
+## What you WILL do
+
+- Explain concepts using multiple analogies and representations (visual, verbal, code).
+- Debug code by asking the learner to explain their logic first, then guiding them to the bug.
+- Generate exercises that target specific skills, with clear difficulty levels (beginner, intermediate, advanced).
+- Use Socratic questioning: ask the learner to predict output, identify errors, or compare approaches.
+- Provide feedback on the learner's code that is specific, actionable, and encouraging.
+- Reference standard CS curriculum topics (arrays, linked lists, trees, graphs, sorting, searching, recursion, dynamic programming, etc.).
+
+## What you WON'T do
+
+- Write a complete solution to an assignment without the learner first attempting it.
+- Evaluate or grade the learner's work — that is the instructor's role.
+- Pretend to know the learner's course syllabus, deadlines, or grading rubric unless they provide it.
+- Give advice on academic dishonesty, plagiarism, or cheating.
+- Provide personal academic counseling (course selection, major decisions).
+- Output code that is intentionally obfuscated, malicious, or violates academic integrity.

package/registry/families/agent-runtime-cs-tutor-ts/files/README.md

@@ -0,0 +1,29 @@
+# CS Tutor Agent Runtime
+
+A Cloudflare Worker agent that provides CS tutoring: explains concepts, debugs code, and generates exercises.
+
+## Getting Started
+
+1. Install dependencies: `npm install`
+2. Set environment variables: `TANGLE_API_KEY`
+3. Deploy: `npx wrangler deploy`
+
+## Routes
+
+- `POST /api/chat` — Main chat endpoint (bearer auth)
+- `GET /api/health` — Health check
+
+## Capabilities
+
+- `explain-concept` — Explain a CS concept
+- `debug-code` — Debug user-provided code
+- `generate-exercise` — Generate a practice exercise
+
+## Templates
+
+- `templates/explain-concept.md`
+- `templates/debug-code.md`
+- `templates/generate-exercise.md`
+
+## License
+MIT

package/registry/families/agent-runtime-cs-tutor-ts/files/TOOLS.md

@@ -0,0 +1,23 @@
+# TOOLS — agent-runtime-cs-tutor-ts
+
+The bundle inherits all primitives from `agent-base:secure`: `secrets`, `workspace`, `webhook-in`, `webhook-out`, `schedule`, `identity`, `audit`. Plus generic agent tools: `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Bash`, `WebFetch`.
+
+This file lists **domain-specific tools the operator MAY add** if the deployment needs them. Each entry is intent — not implementation. The agent itself can build any of these on demand using `Bash`/`Write` if the operator hasn't.
+
+## Domain tools the operator may want
+
+Stub list — replace with role-specific entries. Keep ≤10 domain tools per deployment; more is fragmentation. Each tool should be:
+- Single-purpose
+- JSON output
+- ≤100 LOC
+- Listed here when added
+
+| Tool | Intent | Notes |
+|---|---|---|
+| `explain-concept` | Concrete tool implementing the `explain-concept` capability | Operator implements when needed |
+| `debug-code` | Concrete tool implementing the `debug-code` capability | Operator implements when needed |
+| `generate-exercise` | Concrete tool implementing the `generate-exercise` capability | Operator implements when needed |
+
+## Build a new tool when you need it
+
+The agent's job includes building tools when the measurement doesn't exist. New tools should be small, JSON-output, single-purpose. Add an entry here via PR after shipping.

package/registry/families/agent-runtime-cs-tutor-ts/files/agent.json

@@ -0,0 +1,38 @@
+{
+  "name": "cs-tutor",
+  "description": "CS tutoring agent bundle — teaches programming fundamentals, data structures, algorithms, and debugging. Composes the agent-runtime substrate with the blocks output layer on the Tangle floor. Advisory only — never replaces a human instructor or academic advisor.",
+  "version": "0.1.0",
+  "tags": [
+    "agent-runtime",
+    "cs-tutor",
+    "programming-tutor",
+    "education",
+    "cloudflare-worker"
+  ],
+  "prompt": {
+    "systemPromptFile": "AGENTS.md"
+  },
+  "tools": {
+    "filesystem": true,
+    "shell": true,
+    "router": true
+  },
+  "permissions": {
+    "filesystem.write": "ask",
+    "shell.exec": "ask",
+    "network": "ask"
+  },
+  "resources": {
+    "files": [
+      {
+        "source": "methodology/"
+      },
+      {
+        "source": "README.md"
+      },
+      {
+        "source": "TOOLS.md"
+      }
+    ]
+  }
+}

package/registry/families/agent-runtime-cs-tutor-ts/files/methodology/debug-code.md

@@ -0,0 +1,33 @@
+# Debug Code Template
+
+## Purpose
+Guide the learner to find and fix bugs in their code.
+
+## Structure
+
+1. **Ask the learner to describe what the code should do.**
+2. **Ask the learner to trace through the code manually** for a small input.
+3. **Identify the symptom** (wrong output, error, infinite loop).
+4. **Narrow down the location** of the bug using binary search or print statements.
+5. **Guide the learner to the root cause** with a hint, not the fix.
+6. **Once found, explain why it's a bug** and how to fix it.
+7. **Suggest a test case** that would have caught the bug.
+
+## Example
+
+**Learner's code:**
+```python
+def sum_list(lst):
+    total = 0
+    for i in range(len(lst)):
+        total += lst[i]
+    return total
+```
+
+**Symptom:** Returns 0 for empty list (correct) but also for `[1,2,3]` returns 0.
+
+**Hint:** Check the loop variable — are you sure `i` is being used correctly?
+
+**Root cause:** `i` is not used; the loop adds `lst[i]` but `i` is the index, not the element. Should be `for i in lst: total += i`.
+
+**Test case:** `sum_list([1])` should return 1.

package/registry/families/agent-runtime-cs-tutor-ts/files/methodology/explain-concept.md

@@ -0,0 +1,34 @@
+# Explain Concept Template
+
+## Purpose
+Provide a clear, multi-faceted explanation of a CS concept.
+
+## Structure
+
+1. **Name the concept** and its importance.
+2. **Give a high-level intuition** (one-sentence analogy or real-world parallel).
+3. **Break down the mechanics** step by step, using pseudocode or diagrams if helpful.
+4. **Show a concrete example** with code (Python, JavaScript, or pseudocode).
+5. **Highlight common misconceptions** and how to avoid them.
+6. **Offer a practice question** to check understanding.
+
+## Example
+
+### Concept: Recursion
+
+**Intuition:** Recursion is like Russian nesting dolls — each doll contains a smaller version of itself until you reach the smallest one.
+
+**Mechanics:** A recursive function calls itself with a smaller input until it reaches a base case.
+
+**Code:**
+```python
+def factorial(n):
+    if n == 0:  # base case
+        return 1
+    else:
+        return n * factorial(n-1)  # recursive call
+```
+
+**Common misconception:** "Recursion is infinite." No — every recursive function must have a base case that stops the recursion.
+
+**Practice:** Write a recursive function to compute the nth Fibonacci number.

package/registry/families/agent-runtime-cs-tutor-ts/files/methodology/generate-exercise.md

@@ -0,0 +1,44 @@
+# Generate Exercise Template
+
+## Purpose
+Create a practice exercise targeting a specific skill.
+
+## Structure
+
+1. **Skill:** Name the skill (e.g., "implement a binary search tree").
+2. **Difficulty:** Beginner / Intermediate / Advanced.
+3. **Prompt:** Clear problem statement with input/output examples.
+4. **Constraints:** Time/space complexity, language, libraries.
+5. **Hints:** Progressive hints (optional, for the tutor to reveal).
+6. **Solution:** Full solution with explanation (for the tutor's reference, not to be shown to the learner unless they ask after attempting).
+
+## Example
+
+**Skill:** Implement a function that reverses a linked list.
+
+**Difficulty:** Intermediate
+
+**Prompt:** Write a function `reverse(head)` that takes the head of a singly linked list and returns the new head after reversing the list. Each node has `val` and `next` properties.
+
+**Example:**
+Input: 1 -> 2 -> 3 -> null
+Output: 3 -> 2 -> 1 -> null
+
+**Constraints:** O(n) time, O(1) space.
+
+**Hints:**
+1. Use three pointers: prev, curr, next.
+2. Iterate through the list, reversing the `next` pointer of each node.
+
+**Solution:**
+```python
+def reverse(head):
+    prev = None
+    curr = head
+    while curr:
+        next_temp = curr.next
+        curr.next = prev
+        prev = curr
+        curr = next_temp
+    return prev
+```

package/registry/families/agent-runtime-cs-tutor-ts/files/methodology/index.json

@@ -0,0 +1,25 @@
+{
+  "entries": [
+    {
+      "id": "explain-concept",
+      "capability": "explain-concept",
+      "path": "./explain-concept.md",
+      "tags": ["methodology", "teaching", "concept"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "debug-code",
+      "capability": "debug-code",
+      "path": "./debug-code.md",
+      "tags": ["methodology", "debugging", "code-review"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "generate-exercise",
+      "capability": "generate-exercise",
+      "path": "./generate-exercise.md",
+      "tags": ["methodology", "practice", "exercise"],
+      "version": "0.1.0"
+    }
+  ]
+}