@tangle-network/starter-foundry 0.7.2 → 0.13.0

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

@@ -0,0 +1,29 @@
+# agent-runtime-architect-ts
+
+Software architecture advisor agent bundle — system design, trade-off analysis, and architecture decision records.
+
+## Overview
+
+This agent works alongside a technical lead, CTO, or engineering team to provide structured thinking from the software-architecture canon. It is advisory only and never replaces hands-on engineering leadership or board-level technical diligence.
+
+## Capabilities
+
+- **system-design**: Use the system design canvas to design or review a system architecture.
+- **trade-off-analysis**: Analyze trade-offs between architectural options based on quality attributes.
+- **architecture-decision-record**: Capture and manage architecture decisions using ADRs.
+
+## Usage
+
+Deploy as a Cloudflare Worker. The agent exposes two routes:
+- `/api/chat` — authenticated chat endpoint for interacting with the agent
+- `/api/health` — health check endpoint
+
+## Configuration
+
+Set the following environment variables:
+- `TANGLE_API_KEY`: API key for Tangle router
+- `AGENT_NAME`: Name of the agent (default: "architect")
+
+## License
+
+Proprietary.

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

@@ -0,0 +1,23 @@
+# TOOLS — agent-runtime-architect-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 |
+|---|---|---|
+| `system-design` | Concrete tool implementing the `system-design` capability | Operator implements when needed |
+| `trade-off-analysis` | Concrete tool implementing the `trade-off-analysis` capability | Operator implements when needed |
+| `architecture-decision-record` | Concrete tool implementing the `architecture-decision-record` 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-architect-ts/files/agent.json

@@ -0,0 +1,38 @@
+{
+  "name": "architect",
+  "description": "Software architecture advisor agent bundle — system design, trade-off analysis, and architecture decision records. Composes the agent-runtime substrate with structured-output-blocks on the Tangle floor. Advisory only — never replaces hands-on engineering leadership or board-level technical diligence.",
+  "version": "0.1.0",
+  "tags": [
+    "agent-runtime",
+    "software-architecture",
+    "advisory-agent",
+    "architect",
+    "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-architect-ts/files/methodology/architecture-decision-record.md

@@ -0,0 +1,157 @@
+# Architecture Decision Record (ADR) Template
+
+## Purpose
+Capture an architectural decision in a durable, auditable record
+that future engineers can read, critique, and either honor or
+explicitly supersede. ADRs are the institutional memory of why a
+system is the way it is.
+
+## When to use
+Trigger when the user is making a non-trivial architectural choice:
+new dependency, new service, new data store, new auth model, new
+deployment substrate, new SLA. Don't ADR every PR; do ADR every
+decision a future engineer will ask "why did we…" about.
+
+## Format
+
+Each ADR is a single markdown file, numbered (`0007-use-postgres-
+for-billing.md`), and immutable once accepted (later ADRs can
+supersede; existing ones do not get rewritten).
+
+### ADR-NNNN: [Short title]
+
+#### Status
+One of: Proposed / Accepted / Deprecated / Superseded by ADR-XXXX /
+Rejected.
+
+Status changes are appended to the file with date and reason — never
+deleted.
+
+#### Date
+YYYY-MM-DD when the status was set.
+
+#### Context
+
+- The problem being solved (1–3 sentences).
+- The forces in play (technical, organizational, business).
+- The constraints (budget, timeline, expertise, regulatory).
+- What is *not* in scope.
+
+Avoid vagueness here. "Improve performance" is not context;
+"the order-export endpoint p99 is 4.8s and our SLA is 1.0s; we
+have ~3 weeks; the team has Postgres expertise but not
+ClickHouse" is.
+
+#### Decision
+
+- The chosen path, stated unambiguously: "We will <do X> by
+  <doing Y>."
+- The mechanism: how this decision is implemented.
+- The boundary: where the decision applies and where it does not.
+
+#### Alternatives considered
+
+For each alternative seriously considered:
+- Description.
+- Why it was *not* chosen — the specific blocker (cost, risk,
+  capacity, ergonomics).
+
+The alternatives section is the most-read part of the doc later.
+Engineers re-evaluating the decision want to see the option they're
+about to revisit was already on the table.
+
+#### Consequences
+
+- **Positive**: what this enables / fixes / clarifies.
+- **Negative**: what this costs / forecloses / risks.
+- **Neutral**: secondary effects worth naming.
+
+Don't pretend negatives don't exist. A decision with no negative
+consequences is either trivial or under-analyzed.
+
+#### Compliance / enforcement
+
+- How will the decision be honored in code (lint rule, CI gate,
+  architectural fitness function, framework constraint)?
+- How will violations be detected?
+- What's the override path if a future case genuinely warrants
+  deviation?
+
+#### Review trigger
+
+- Conditions under which this decision should be re-evaluated:
+  scale threshold, vendor change, regulatory change, expiration of
+  vendor contract, new internal capability.
+- Without a review trigger, accepted ADRs ossify even when the
+  underlying assumptions have changed.
+
+## Worked example (sketch)
+
+> ADR-0023: Use Postgres for the billing event log
+>
+> Status: Accepted
+> Date: 2026-04-26
+>
+> Context: billing requires append-only event log with strict
+> ordering, immediate read consistency, and 7-year retention.
+> Volume: ~2K events/sec peak. Team has Postgres expertise; we
+> already operate Postgres at this scale for orders.
+>
+> Decision: store billing events in a dedicated Postgres
+> database, partitioned by month. Reads via materialized views
+> kept fresh by triggers.
+>
+> Alternatives considered:
+> - **Kafka + S3**: high write throughput; but read consistency
+>   requires Kafka Streams or downstream materialization, adding
+>   ops surface. No team expertise.
+> - **DynamoDB**: managed; but query patterns require multiple
+>   GSIs and the per-RU cost projections exceed Postgres TCO at
+>   our volume.
+> - **ClickHouse**: read-optimized; but eventual-consistency
+>   semantics conflict with billing accuracy requirements.
+>
+> Consequences:
+> - Positive: leverages existing Postgres operational expertise;
+>   strong consistency; cheap at our volume.
+> - Negative: ceiling at ~10K events/sec without sharding;
+>   re-evaluate at 5K/sec sustained.
+> - Risk: 7-year retention will require partition lifecycle
+>   automation; assigned to platform-team.
+>
+> Compliance: lint rule blocks new billing event writers from
+> targeting any other store; weekly partition-health alert.
+>
+> Review trigger: sustained >5K events/sec, OR cost crosses
+> $X/month, OR Postgres EOL announcement, OR if new compliance
+> regime requires immutability beyond append-only (e.g., WORM
+> storage).
+
+## Common ADR failures
+
+1. **Status never updated.** ADRs go stale; review on the
+   trigger.
+2. **No alternatives section.** Future engineers can't tell if
+   the decision was deliberate or default.
+3. **Vague consequences.** "May affect performance" — quantify
+   or omit.
+4. **No enforcement.** ADRs without lint / CI / framework
+   support drift; the decision exists on paper only.
+5. **One huge ADR.** Bundling 5 decisions hides the disagreement
+   on each. Split.
+6. **Late ADR.** ADRs after the code has shipped are
+   archaeology, not decision-making. Write them before or
+   alongside the work.
+
+## Output
+
+Wrap in `:::artifact` with `template: architecture-decision-record`
+and the ADR number. Include the full ADR body.
+
+## Refusal
+
+The agent will not:
+- Approve an ADR without alternatives or enforcement section.
+- Mark an ADR "Accepted" without a stated review trigger.
+- Rewrite an Accepted ADR; it will instead author a superseding
+  ADR with a back-link.

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

@@ -0,0 +1,25 @@
+{
+  "entries": [
+    {
+      "id": "system-design-canvas",
+      "capability": "system-design",
+      "path": "./system-design-canvas.md",
+      "tags": ["methodology", "system-design", "c4-model"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "trade-off-analysis",
+      "capability": "trade-off-analysis",
+      "path": "./trade-off-analysis.md",
+      "tags": ["methodology", "trade-off", "quality-attributes"],
+      "version": "0.1.0"
+    },
+    {
+      "id": "architecture-decision-record",
+      "capability": "architecture-decision-record",
+      "path": "./architecture-decision-record.md",
+      "tags": ["methodology", "adr", "decision-capture"],
+      "version": "0.1.0"
+    }
+  ]
+}

package/registry/families/agent-runtime-architect-ts/files/methodology/system-design-canvas.md

@@ -0,0 +1,33 @@
+# System Design Canvas
+
+## Context
+- **System name:**
+- **Stakeholders:**
+- **Goals:**
+- **Non-functional requirements (quality attributes):**
+  - Latency:
+  - Throughput:
+  - Availability:
+  - Consistency:
+  - Cost:
+  - Security:
+  - Scalability:
+
+## Architecture Overview
+- **Architectural style:** (e.g., microservices, event-driven, layered, hexagonal)
+- **Key components:**
+  - Component 1: responsibility
+  - Component 2: responsibility
+- **Data flow:** (describe how data moves through the system)
+
+## Key Decisions
+- Decision 1: rationale
+- Decision 2: rationale
+
+## Trade-offs
+- Trade-off 1: what is gained vs. what is lost
+- Trade-off 2: what is gained vs. what is lost
+
+## Risks & Mitigations
+- Risk 1: mitigation
+- Risk 2: mitigation

package/registry/families/agent-runtime-architect-ts/files/methodology/trade-off-analysis.md

@@ -0,0 +1,146 @@
+# Trade-off Analysis Template
+
+## Purpose
+Compare 2–4 architectural options against the system's quality
+attributes, surface the trade-offs explicitly, and produce a
+defensible recommendation. Trade-off analysis is the substrate of
+a good ADR; ADR captures the decision, this template captures the
+reasoning.
+
+## When to use
+Trigger when a decision has more than one viable path and the
+right answer depends on which qualities the system values most.
+Database choice, sync vs async, monolith vs microservices,
+build vs buy, framework selection.
+
+## Method
+
+1. **Frame the decision.** State the question in one sentence.
+   "Should the order pipeline be synchronous request/response or
+   async event-driven?"
+2. **Enumerate options.** 2–4 distinct paths. Each gets a name,
+   a one-paragraph description, and a sketch of the
+   implementation shape. More than 4 options usually means the
+   decision space hasn't been pruned; consolidate.
+3. **Pick quality attributes that matter.** Don't compare on
+   "everything"; pick the 5–8 attributes whose values differ
+   meaningfully across options. Common attributes:
+   - **Performance**: latency (p50, p99), throughput, scalability
+     ceiling.
+   - **Availability**: uptime, blast radius of failure, recovery
+     time.
+   - **Consistency**: strong / eventual / causal; staleness
+     tolerance.
+   - **Durability**: data-loss tolerance, backup integrity, RPO.
+   - **Cost**: TCO including ops, license, compute, storage,
+     egress, on-call burden.
+   - **Security**: attack surface, data-at-rest exposure, blast
+     radius.
+   - **Operability**: monitoring, debugging, on-call experience,
+     deploy/rollback.
+   - **Evolvability**: how this option ages with scale, with
+     regulatory change, with team turnover.
+   - **Time to value**: how soon the option ships.
+   - **Vendor risk**: lock-in, EOL exposure, pricing power.
+4. **Score per attribute, per option.**
+   - Use a consistent scale (1–5 or H/M/L). Justify each cell
+     with one sentence — never a bare number.
+   - Where data exists, put numbers (latency, $/month). Where
+     it doesn't, name the assumption.
+   - **Asymmetric weight** the attributes by what the system
+     actually values. Latency-critical systems care less about
+     vendor risk; regulated systems care less about time to
+     value. The weight matrix is a forcing function — without
+     it, comparison is naïve weighted-average.
+5. **Identify the dominant trade-off.** Most decisions reduce to
+   one or two key tensions:
+   - Consistency vs availability (CAP).
+   - Latency vs durability.
+   - Coupling vs autonomy.
+   - Cost vs flexibility.
+   - Time to value vs technical debt.
+   Naming the dominant trade-off lets the team make a
+   *decision*, not a feature comparison.
+6. **Sensitivity analysis.** Vary the most important assumptions
+   (volume, latency target, cost per unit) and check whether the
+   ranking flips. If a small change in one input flips the
+   answer, the decision is fragile — name that.
+7. **Recommend with a fallback.** Make a recommendation. Also
+   name the second-best, and the conditions under which the team
+   should switch.
+8. **Surface what isn't yet known.** Many trade-offs depend on
+   data the team doesn't have yet (real production load, real
+   error rates). Explicitly mark those as assumptions and tie
+   them to the ADR's review trigger.
+
+## Worked example (sketch)
+
+Question: Should the order pipeline be synchronous (HTTP RPC
+with strong consistency) or asynchronous (event-driven with
+eventual consistency)?
+
+| Attribute      | Sync (RPC)            | Async (events)         | Weight |
+|----------------|------------------------|------------------------|--------|
+| Latency p99    | 280ms (measured)       | ~80ms publish + 1–5s settle | High |
+| Availability   | 99.5%; cascade risk    | 99.95%; partial degradation | High |
+| Consistency    | Strong (read-after-write) | Eventual (1–5s lag)    | Medium |
+| Cost           | $X/mo                  | $1.4×X/mo (broker)     | Medium |
+| Operability    | Existing patterns      | New broker to operate  | Medium |
+| Evolvability   | Tight coupling         | Loose coupling         | High |
+| Time to value  | 2 weeks                | 6 weeks                | Medium |
+
+Dominant trade-off: read-after-write consistency vs availability /
+evolvability. Sync wins on consistency and time-to-value; async
+wins on availability and evolvability under future scale.
+
+Recommendation: async (events) for new pipelines; keep sync for
+existing high-consistency reads. Re-evaluate if event broker
+operational cost exceeds $Y/mo or async lag exceeds 5s p99.
+
+## Common analysis failures
+
+1. **Comparing on everything.** A 20-attribute matrix dilutes
+   signal. Prune to the attributes that actually differ.
+2. **No weights.** All attributes treated equal, hiding which
+   the org cares about.
+3. **Numerical theater.** Adding 1–5 scores when the cells are
+   guesses gives false precision.
+4. **Forgotten op-cost.** Many "cheap" options are cheap in
+   compute and expensive in on-call burden.
+5. **Status-quo bias.** Existing tech wins by default unless the
+   review forces a real comparison.
+6. **No second-best with switch conditions.** Without it, the
+   team can't recover when assumptions break.
+7. **Ignoring carrying cost.** Some options have low entry cost
+   and high removal cost (vendor lock-in, schema migration). Name
+   the exit path.
+
+## Output
+
+```
+:::artifact
+template: trade-off-analysis
+question: "..."
+options:
+  - { name: "A", desc: "..." }
+  - ...
+attributes:
+  - { name: "latency-p99", weight: "high" }
+  - ...
+matrix:
+  A: { latency-p99: { score: 4, note: "280ms measured" }, ... }
+  B: { ... }
+dominant-trade-off: "..."
+sensitivity: "..."
+recommendation: "B with fallback to A under conditions X, Y"
+unknowns: [...]
+:::
+```
+
+## Refusal
+
+The agent will not:
+- Recommend an option without surfacing the dominant trade-off.
+- Score attributes that don't differ meaningfully across options.
+- Treat status quo as the default; require it to be evaluated on
+  the same matrix.

package/registry/families/agent-runtime-architect-ts/manifest.json

@@ -0,0 +1,146 @@
+{
+  "id": "agent-runtime-architect-ts",
+  "description": "Software architecture advisor agent bundle \u2014 system design, trade-off analysis, and architecture decision records. Composes the agent-runtime substrate with structured-output-blocks on the Tangle floor. Advisory only \u2014 never replaces hands-on engineering leadership or board-level technical diligence.",
+  "tags": [
+    "agent-runtime",
+    "software-architecture",
+    "advisory-agent",
+    "architect",
+    "cloudflare-worker"
+  ],
+  "taxonomy": {
+    "language": "markdown",
+    "runtime": "cloudflare-worker",
+    "surface": "agent-runtime"
+  },
+  "includes": [
+    "agent-base:tangle",
+    "agent-base:secure",
+    "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-architect",
+    "agentName": "architect",
+    "publicVars": [
+      "AGENT_NAME"
+    ],
+    "routes": [
+      {
+        "path": "/api/chat",
+        "auth": "bearer",
+        "callsTools": [
+          "system-design",
+          "trade-off-analysis",
+          "adr"
+        ]
+      },
+      {
+        "path": "/api/health",
+        "auth": "none",
+        "callsTools": []
+      }
+    ],
+    "declaredCapabilities": [
+      "system-design",
+      "trade-off-analysis",
+      "architecture-decision-record"
+    ],
+    "runtime": {
+      "sandbox": "tangle",
+      "noNewPrivileges": true,
+      "capDrop": "ALL"
+    },
+    "stakes": "moderate",
+    "advisoryOnly": true,
+    "outboundDomains": [
+      "api.tangle.tools"
+    ],
+    "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/system-design-canvas.md",
+      "target": "methodology/system-design-canvas.md"
+    },
+    {
+      "source": "files/methodology/trade-off-analysis.md",
+      "target": "methodology/trade-off-analysis.md"
+    },
+    {
+      "source": "files/methodology/architecture-decision-record.md",
+      "target": "methodology/architecture-decision-record.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": [
+      "software-architect-agent",
+      "software architect agent",
+      "software-architect",
+      "software architect",
+      "system-design-agent",
+      "system design agent",
+      "architecture-advisor",
+      "architecture advisor"
+    ],
+    "tier2": [
+      "system-design",
+      "system design",
+      "trade-off-analysis",
+      "trade off analysis",
+      "architecture-decision-record",
+      "architecture decision record",
+      "adr",
+      "non-functional-requirements",
+      "non functional requirements",
+      "quality-attributes",
+      "quality attributes"
+    ],
+    "tier3": [],
+    "archetypes": [
+      "agent-in-sandbox",
+      "advisory-agent"
+    ]
+  }
+}