@inneranimalmedia/agentsam-sdk 2.4.1 → 2.5.0

package/skills/agentsam-app-fundamentals/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: agentsam-app-fundamentals
+description: >
+  Keep application-building work grounded in execution domains, contracts, credentials,
+  dependency graphs, AST evidence, Merkle evidence, and explicit I/O boundaries. Use when
+  adding or reviewing a feature, service, package, API, auth flow, secret, integration,
+  frontend/backend boundary, worker, webhook, or external credentialed destination. Also
+  use for quick reminders when a large codebase makes the underlying mechanics hard to
+  keep in working memory. Triggers on "app fundamentals", "quick bytes", "trust boundary",
+  "client secret", "redirect URI", "frontend/backend", "AST", "Merkle", "contract drift",
+  "service boundary", "credentialed destination", and "where should this logic live".
+metadata:
+  short-description: "Application-building laws: ownership, contracts, credentials, graphs, AST, and Merkle evidence"
+  aliases:
+    - app-fundamentals
+    - application-fundamentals
+    - quick-bytes
+user-invocable: true
+---
+
+# AgentSam Application Fundamentals
+
+Use this skill as a **small engineering compass**, not a giant textbook. A large
+platform becomes manageable when every feature can answer a few mechanical
+questions: who executes it, who owns authority, what contract crosses the boundary,
+what credential is used, what it depends on, and what evidence proves the change.
+
+## Quick bytes
+
+- **Execution domain:** trust follows who controls the machine/runtime, not the folder name.
+- **Browser/client:** user-controlled and therefore observable/tamperable. Never make it the final authority for security or privileged state changes.
+- **Server/backend:** operator-controlled execution. Re-verify identity, authorization, ownership, prices, permissions, and other invariants here.
+- **Import:** a dependency edge. **Export:** a public contract another module may depend on.
+- **AST:** parsed code structure. Use it to identify symbols, imports/exports, calls, environment access, and execution-domain contradictions without relying on text grep alone.
+- **Dependency graph/DAG:** the map of what depends on what. It determines blast radius, build order, affected tests, and what can run in parallel.
+- **Schema/contract:** the agreed shape at a boundary. Compile-time types help; runtime validation proves real external data matches the contract.
+- **Merkle/content hash:** identity for observed bytes. A changed root proves something changed; an unchanged root proves the captured content is identical under the same policy.
+- **Semantic metadata root:** identity for the indexed/classified view of those bytes. It can change when execution classification or parser-derived meaning changes even when content does not.
+- **Client ID:** usually a public application identifier. **Client secret/API secret:** a credential proving authority; keep it out of browser code and public bundles.
+- **Redirect URI:** an explicitly registered destination for an authorization flow. The provider returns to the callback; your backend verifies the flow, establishes your app session, then chooses the final in-app destination.
+- **Firewall/WAF:** an ingress filter. It reduces hostile traffic; it does not replace authentication, authorization, ownership checks, runtime validation, or least privilege.
+- **Hook:** code that runs automatically because a lifecycle event occurred. Treat hooks as explicit I/O contracts, not mystery scripts.
+
+If one of those concepts is fuzzy for the current task, read the matching reference
+before editing.
+
+## The six questions for every feature
+
+Before changing code, be able to answer:
+
+1. **User behavior:** what can the user now do?
+2. **Execution owner:** which runtime is trusted to make the decision or perform the side effect?
+3. **Contract:** what request/event/type/schema crosses each boundary?
+4. **State:** what is ephemeral, browser-local, durable, cached, or externally owned?
+5. **Credentialed destinations:** which external systems are called, from which runtime, with which public IDs/secrets/scopes?
+6. **Proof:** which tests, AST/index evidence, Merkle receipt, runtime response, or observable metric proves it works?
+
+If a feature cannot answer these, it is not ready to be called complete.
+
+## Build vertical slices, not disconnected layers
+
+For application work, trace the real behavior end to end:
+
+```text
+user action
+  -> client intent
+  -> validated boundary contract
+  -> trusted server/domain operation
+  -> database/service/provider side effect
+  -> response/event
+  -> client state/render
+  -> test + runtime proof
+```
+
+A button without the trusted operation behind it is incomplete. A backend endpoint
+without a real consumer may be dead surface area. A shared type without runtime
+validation is not proof that an external system obeyed the type.
+
+## Credentialed-destination card
+
+Whenever a feature talks to Google, GitHub, Cloudflare, Stripe, a model provider,
+a database, another Worker/service, or any other privileged destination, write down
+this card before wiring it:
+
+```text
+Destination
+  provider/service:
+  purpose:
+  caller execution domain:
+  public identifier(s):
+  secret credential(s):
+  credential owner/runtime:
+  allowed origin/host:
+  callback/redirect/webhook URI(s):
+  scopes/permissions:
+  request contract:
+  response contract:
+  timeout/retry/idempotency:
+  failure behavior:
+  audit/observability:
+  rotation/revocation path:
+```
+
+This turns "a pile of env vars" into an explicit relationship. Environment variable
+names are configuration labels; the credential value is the sensitive authority.
+Validate required configuration at boot or boundary entry and fail clearly.
+
+Read `references/trust-credentials-and-destinations.md` for auth/OAuth and destination
+mechanics.
+
+## Graph law for packages/services/apps
+
+As a system grows, do not rely on remembering which file "goes with" another file.
+Make coupling machine-visible:
+
+```text
+package/service A
+  imports / calls / subscribes to
+package/service B
+  implements contract C
+  owns state D
+  uses credential E
+```
+
+Prefer a single contract authority for cross-surface behavior: a shared type/schema,
+OpenAPI/GraphQL/Protobuf definition, event schema, or other versioned interface. Use
+AST/import graphs and package metadata to determine affected dependents instead of
+manually searching a million-line repository.
+
+Read `references/graphs-contracts-ast-merkle.md` for the deeper model.
+
+## AgentSam evidence tools
+
+Prefer deterministic evidence before broad model reasoning:
+
+```bash
+agentsam inspect --json
+agentsam inspect --execution-domain browser --view files --json
+agentsam security scan --path .
+agentsam merkle ...
+agentsam index ...
+agentsam search ...
+```
+
+Use repository/index tools to narrow the relevant graph. Do not dump the whole repo
+or all tool schemas into context.
+
+## Rules while building
+
+1. Never infer trust from `frontend/`, `backend/`, `worker/`, or `shared/` names alone; verify execution reality.
+2. Never put a long-lived secret into code delivered to a user-controlled runtime.
+3. Never let client-side validation be the only security or correctness check.
+4. Never introduce a second contract authority when an existing canonical schema/type can be extended.
+5. Never change a shared contract without identifying downstream dependents.
+6. Never treat a Merkle hash as proof of correctness; it proves observed identity/change, not behavior.
+7. Never treat AST/index output as infallible; account for parser coverage, generated/framework code, and explicit classification overrides.
+8. Never let a hook silently mutate unrelated state. Bound its inputs, outputs, permissions, timeout, and failure policy.
+9. Never call a credential "just an env var." Record who owns it, where it may exist, and what it authorizes.
+10. Never ship a cross-layer feature from screenshots alone. Exercise the real I/O path.
+
+## Handoff to progression guard
+
+Once the feature's boundaries are coherent, use `agentsam-progression-guard` to decide
+**when and where those invariants must be re-proven** during commit, CI, deploy, and
+runtime promotion.

package/skills/agentsam-app-fundamentals/references/graphs-contracts-ast-merkle.md

@@ -0,0 +1,89 @@
+# Graphs, Contracts, AST, and Merkle Evidence
+
+## The codebase is a graph
+
+A large application is easier to reason about when you stop treating it as a folder
+maze and start treating it as a graph:
+
+```text
+files -> symbols -> imports/calls -> packages -> services -> external destinations
+```
+
+The graph answers questions humans should not have to remember:
+
+- If package C changes, which apps depend on it?
+- Which browser entrypoints can reach this server-only module?
+- Which route consumes this schema?
+- Which service owns a database write?
+- Which packages can build/test in parallel?
+- Which consumers must be revalidated after a contract change?
+
+A DAG is especially useful for build/test ordering when cycles are absent or have been
+made explicit.
+
+## AST is structure, not text coincidence
+
+An Abstract Syntax Tree is the parsed structural representation of source code. It can
+reliably distinguish function declarations, imports, calls, environment accesses,
+and other syntax that a plain text search can only approximate.
+
+AgentSam should use AST evidence to derive dependency and execution-boundary facts,
+then preserve parser coverage/errors so an agent knows where certainty ends.
+
+Useful AST-derived facts include:
+
+- imports/exports and resolved local edges;
+- symbol declarations and references;
+- server/runtime-only dependency use;
+- environment variable access names (never secret values);
+- browser-reachable versus server-owned code;
+- contract/schema ownership hints.
+
+## Contracts make coupling explicit
+
+For a frontend/backend or service/service boundary, prefer one canonical contract
+source. Depending on the system that can be a TypeScript package, runtime schema,
+OpenAPI document, GraphQL schema, Protobuf definition, event schema, or equivalent.
+
+Compile-time types catch code drift before build. Runtime validation catches real data
+that violates the contract after types have been erased or when the caller is outside
+the type system. Contract tests can prove independent producer/consumer systems still
+agree.
+
+## Merkle is the evidence identity layer
+
+Merkle hashing gives a deterministic identity to a captured file tree. If one included
+file changes, the root changes. This makes before/after receipts cheap to compare and
+lets CI/deploy systems cache or target work by content identity.
+
+AgentSam separates two identities:
+
+```text
+content root
+  observed included bytes/paths
+
+semantic metadata root
+  classified/indexed meaning derived from those bytes
+```
+
+The semantic root can change after a classifier/parser upgrade or execution-domain
+classification change even when source bytes remain identical. That distinction is
+important: source identity and interpretation identity answer different questions.
+
+## The repair proof loop
+
+For structural repairs, prefer:
+
+```text
+snapshot A
+  -> contradiction finding + evidence refs
+  -> isolated bounded repair
+  -> build/type/test/security checks
+  -> snapshot B
+  -> prove target contradiction disappeared
+  -> prove no disallowed new contradictions
+  -> emit receipt
+```
+
+The model may propose the repair, but deterministic evidence should decide whether the
+repair actually satisfied the invariant.

package/skills/agentsam-app-fundamentals/references/trust-credentials-and-destinations.md

@@ -0,0 +1,99 @@
+# Trust, Credentials, and Credentialed Destinations
+
+## Trust is about execution ownership
+
+The useful distinction is not "frontend equals UI" and "backend equals logic."
+The useful distinction is who controls execution.
+
+A browser, mobile client, or other user-controlled runtime can be inspected and
+modified by that user. Treat requests from it as claims that the trusted side must
+validate. Server-owned runtimes can hold privileged credentials and enforce durable
+invariants, but they still must authenticate callers and apply least privilege.
+
+## Public identifiers versus credentials
+
+A public client/application ID tells a provider **which registered application** is
+participating. It is often visible in redirect URLs or client configuration and is
+not, by itself, proof of authority.
+
+A client secret, API key, signing key, refresh token, database credential, or similar
+secret is authority-bearing material. Its value belongs only in the runtime that is
+allowed to use that authority. Do not confuse a secret's environment variable name
+with the secret itself.
+
+## OAuth redirect mental model
+
+Keep the endpoints separate:
+
+```text
+/app/auth/login
+  -> creates state / PKCE material as appropriate
+  -> redirects browser to provider authorization endpoint
+
+provider
+  -> authenticates user + consent
+  -> redirects only to registered callback
+
+/app/auth/callback
+  -> verifies state and flow binding
+  -> exchanges code server-to-server when the flow requires it
+  -> validates provider identity claims
+  -> finds/creates local user
+  -> establishes the app's own session
+  -> redirects to the intended in-app destination
+```
+
+The callback is not the user's final product page. It is a security-sensitive
+boundary where the external authorization flow becomes an internal authenticated
+session.
+
+For clients that cannot safely keep a static secret, use the provider's supported
+public-client flow such as Authorization Code + PKCE rather than embedding a secret
+in the client.
+
+## Destination registry mindset
+
+Treat every external system as a typed destination rather than an ad-hoc URL string.
+For each destination record:
+
+- canonical provider/service identity;
+- allowed host/origin and transport;
+- caller execution domain;
+- public IDs versus secret credentials;
+- scopes/permissions;
+- redirect/callback/webhook endpoints;
+- input/output schemas;
+- retry, timeout, idempotency, and rate-limit behavior;
+- audit/logging rules that never emit secrets;
+- rotation/revocation owner.
+
+This is the mechanism that makes `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, a
+callback URI, and a login route understandable as one relationship instead of four
+unrelated strings.
+
+## Defense in depth
+
+Think in layers, each assuming the layer before it can fail:
+
+```text
+internet
+  -> edge/DDoS protection
+  -> firewall/WAF/bot/rate-limit policy
+  -> route/authentication
+  -> authorization + ownership validation
+  -> runtime schema validation
+  -> least-privilege credential/service access
+  -> durable audit/observability
+```
+
+A WAF can reject known-bad traffic, but it cannot know your business ownership rule.
+Authentication can prove a user identity, but it does not automatically prove that
+user may modify a particular record. A valid credential can authenticate a service
+while still being over-privileged. Re-verify at each boundary.
+
+## Fail fast at configuration boundaries
+
+Validate required runtime configuration when the process/worker starts or before the
+first privileged operation. Check presence, expected public/secret classification,
+allowed destination, and format where the provider defines one. Never log the secret
+value to explain a validation failure.

package/skills/agentsam-jr-dev/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: agentsam-jr-dev
+description: >
+  Teach, inspect, build, and revise software in junior-developer-friendly language
+  without replacing real engineering with toy explanations. Use when a user asks
+  what code, HTTP, frontend/backend, APIs, databases, auth, services, workers,
+  repositories, packages, deployments, or application architecture mean; when
+  onboarding someone to an unfamiliar repo; or when explaining why a proposed
+  implementation belongs in a particular layer. Also use while building or
+  reviewing software when the user benefits from understanding the real mechanics.
+  Triggers on "jr dev", "junior dev", "explain this", "what is HTTP", "frontend",
+  "backend", "API", "service", "microservice", "how does this app work", "repo map",
+  "teach me", "break this down", and "why does this go here".
+metadata:
+  short-description: "Teach real software mechanics from the actual repo, then prove the implementation"
+  aliases:
+    - agentsam_jr_dev
+    - jr-dev
+user-invocable: true
+---
+
+# AgentSam Jr Dev
+
+Teach software by connecting **simple mental models to the actual system in front
+of you**. The goal is not to make engineering sound easy. The goal is to make
+real engineering understandable without hiding the mechanics.
+
+A successful Jr Dev answer leaves the user knowing:
+
+1. **what the thing is,**
+2. **why it exists,**
+3. **where it lives in this project,**
+4. **what talks to it,**
+5. **what state or authority it owns,** and
+6. **how to prove it works.**
+
+Do not teach a fake generic architecture when repository evidence is available.
+Inspect first, then explain what is actually there.
+
+## Core behavior
+
+### 1. Start with the smallest useful explanation
+
+Use this progression unless the user asks for a different depth:
+
+- **10-second model** — one plain-language sentence.
+- **mechanics** — the actual request/data/control flow.
+- **repo proof** — name the real files, directories, routes, schemas, or services.
+- **engineering consequence** — explain why the boundary matters when building or changing it.
+
+Example:
+
+> HTTP is the agreed request/response language two programs use to talk over a
+> network. In this repo, the browser calls `/api/models`; the backend route
+> receives that request, uses trusted server-side configuration, and returns a
+> response the frontend can render.
+
+Never stop at an analogy when the user needs the real mechanism.
+
+### 2. Inspect before teaching repo-specific facts
+
+For an unfamiliar project, establish the system shape before making claims:
+
+- project/package manifests,
+- top-level tree,
+- runtime entrypoints,
+- frontend entrypoint and routes,
+- backend/server/worker entrypoint,
+- shared contracts,
+- API/transport boundaries,
+- persistence/storage,
+- auth/identity,
+- environment/config,
+- tests,
+- deployment/runtime configuration.
+
+Prefer deterministic repository/index/search tools over reading giant trees or
+hundreds of files into context. Read the smallest relevant spans that prove the
+explanation.
+
+### 3. Teach boundaries as ownership
+
+When explaining architecture, answer **who owns what**:
+
+- frontend owns presentation and browser interaction,
+- backend owns trusted execution and privileged access,
+- shared/contracts own the shape both sides agree on,
+- database/storage owns durable state,
+- auth owns verified identity,
+- HTTP/RPC/WebSocket is transport, not business logic,
+- workers/servers are runtime entrypoints, not automatically the whole backend,
+- packages expose reusable capabilities,
+- apps compose those capabilities into complete products,
+- services are independently running capabilities with explicit interfaces.
+
+Do not teach folder names as universal laws. A repo may call these layers
+`client/server`, `web/api`, `ui/core`, `worker`, or something else. Explain the
+**responsibility** first, then map it to this repo's names.
+
+Read `references/web-application-fundamentals.md` for the canonical beginner
+mental models and request-flow examples.
+
+### 4. Real application logic is the standard
+
+A polished screen is not proof of a working application. For any build/revision,
+trace the behavior end-to-end:
+
+```text
+user intent
+  -> UI/input
+  -> validated action/request
+  -> trusted business logic
+  -> state/storage/provider side effect
+  -> response/event
+  -> UI state update
+  -> verification
+```
+
+If the requested feature crosses layers, implement and verify every required
+layer. Do not hide missing backend/storage/auth/integration work behind mocked
+frontend state unless the user explicitly asked for a prototype.
+
+Read `references/real-application-logic.md` before claiming a new application,
+service, or cross-layer feature is complete.
+
+### 5. Explain changes in terms of consequences
+
+Instead of:
+
+> I moved this into the backend because that's cleaner.
+
+Prefer:
+
+> This operation needs a secret and writes durable state, so the browser cannot
+> be its authority. The frontend sends the user's intent; the backend verifies
+> it and performs the write. That keeps the secret off the client and gives us
+> one trusted place to enforce validation.
+
+Teach *why*, not just style conventions.
+
+## No-bullshit rules
+
+1. **Never invent a repo architecture.** Inspect it.
+2. **Never call a mock or static screen a finished application** unless the user asked for a mock/prototype.
+3. **Never claim an API/database/service works without exercising its real path** when tools allow verification.
+4. **Never add auth, a database, queues, microservices, or cloud infrastructure just to look production-grade.** Add them when the behavior requires them.
+5. **Never dump huge framework vocabulary before the user has a mental model.** Introduce terms when they explain a real observed mechanism.
+6. **Never equate HTTP with "the backend."** HTTP is one transport. The backend is the trusted logic/runtime behind the interface.
+7. **Never equate a Worker/server file with all business logic.** Prefer thin runtime adapters and explicit application/domain modules when the project warrants it.
+8. **Never teach frontend/backend as a security boundary without checking deployment reality.** Server-side code, browser bundles, secrets, and trust must be verified from the actual framework/runtime.
+9. **Never replace evidence with confidence.** Point to the file, route, schema, test, command, or result that proves the statement.
+10. **Never make "junior" mean patronizing.** Use plain language while preserving the real technical model.
+
+## Repo explanation template
+
+When someone asks "how does this repo/app work?", prefer a compact map like:
+
+```text
+Product
+  what a user can do
+
+Frontend
+  entrypoint:
+  routes/views:
+  state:
+  calls out to:
+
+Backend
+  runtime entrypoint:
+  API/actions:
+  trusted integrations:
+
+Shared contracts
+  types/schemas/events:
+
+State
+  browser-local:
+  durable database/storage:
+
+External systems
+  model providers / Git / payments / etc.:
+
+Request flow
+  user -> frontend -> transport -> backend -> state/provider -> response -> UI
+
+Proof
+  tests / health checks / real execution path:
+```
+
+Only include sections the actual project has.
+
+## Build/revision workflow
+
+For a real task:
+
+1. Restate the user-visible behavior in one sentence.
+2. Identify current architecture from repository evidence.
+3. Identify the authority/state owner for the behavior.
+4. Trace the end-to-end flow before editing.
+5. Reuse existing project patterns/contracts where sound.
+6. Make the smallest coherent cross-layer change.
+7. Exercise the real path.
+8. Explain the result at the user's requested depth.
+
+When debugging, teach the failing boundary:
+
+```text
+input -> frontend -> transport -> backend -> dependency -> persistence -> response
+```
+
+Find the first point where expected and actual behavior diverge.
+
+## Teaching vocabulary
+
+Prefer plain term -> precise term:
+
+- "the browser screen" -> frontend/client
+- "the trusted code doing the work" -> backend/server
+- "the agreed message shape" -> contract/schema
+- "the request language" -> HTTP
+- "a named HTTP endpoint" -> API route/endpoint
+- "long-lived two-way connection" -> WebSocket
+- "saved state" -> persistence/database/storage
+- "proof of who the user is" -> authentication
+- "what that user is allowed to do" -> authorization
+- "a separately running capability" -> service
+- "a small independently deployed service" -> microservice, only when it actually is one
+- "the program's starting door" -> entrypoint
+- "code reused by multiple products" -> package/library
+
+Introduce the precise term immediately after the plain one so the user learns the
+real vocabulary rather than remaining dependent on analogies.