Claude/add jiron support 0112 bjd f wa wsp zhmd1f7o xi4

plan.md

@@ -11,7 +11,14 @@
 
 ### 📋 Context7 GitHub Action Epic
 
-**Status**: 📋 PLANNED  
-**File**: [`tasks/context7-github-action-epic.md`](./tasks/context7-github-action-epic.md)  
-**Goal**: Integrate Context7 GitHub Action to automatically maintain up-to-date code documentation for LLMs and AI code editors  
+**Status**: 📋 PLANNED
+**File**: [`tasks/context7-github-action-epic.md`](./tasks/context7-github-action-epic.md)
+**Goal**: Integrate Context7 GitHub Action to automatically maintain up-to-date code documentation for LLMs and AI code editors
 **Tasks**: 6 tasks (configuration, workflow creation, API integration, release integration, testing, documentation)
+
+### 📋 Jiron Support Epic
+
+**Status**: 📋 PLANNED
+**File**: [`tasks/jiron-support-epic.md`](./tasks/jiron-support-epic.md)
+**Goal**: Enable self-describing APIs that agents browse with one generic capability - replacing explicit tool definitions
+**Tasks**: 8 tasks (jiron-server rule, jiron-api command, jiron-client rule, jiron-component command, dual-render rule, dual-view command, streaming middleware, jiron-agent rule)

tasks/jiron-support-epic-enhanced-prompt.sudo

@@ -0,0 +1,112 @@
+# Enhanced Prompt - Jiron Support
+
+## Goal
+Enable self-describing APIs that agents browse with ONE generic capability - replacing explicit tool definitions (MCP).
+
+## Paradigm Shift
+MCP {
+  model: predefined tools per API
+  requires: tool manifests, schemas, per-API implementations
+  scales: poorly (N tools for N APIs)
+}
+
+Jiron {
+  model: self-describing APIs via hypermedia
+  requires: ONE browse capability
+  scales: infinitely (1 capability for N APIs)
+  analogy: browsers don't need tools.json for websites
+}
+
+## Context
+Jiron {
+  base: Siren semantics + Jade syntax
+  output: valid HTML (browser-renderable, machine-parseable)
+  advantages: hypermedia affordances, code-on-demand, self-documenting APIs
+  key: actions embedded in responses, not predefined in manifests
+}
+
+Siren {
+  type: "application/vnd.siren+json"
+  structure: { class, properties, entities, links, actions, title }
+  entities: URI-addressable resources with state + transitions
+  subEntities: embedded links | embedded representations (require rel)
+  links: navigational (rel, href, class, title, type)
+  actions: behaviors (name, href, method, class, fields)
+}
+
+## Deliverables
+
+JironServer {
+  purpose: AI agent builds Jiron APIs from functional requirements
+  input: task requirements (Given/should format)
+  output: Jiron-compliant hypermedia endpoints
+  rule: create "ai/rules/jiron-server.mdc"
+  command: create "ai/commands/jiron-api.md"
+}
+
+JironClient {
+  purpose: dynamically build web components from Jiron endpoints
+  input: Jiron API endpoint URL
+  output: web components supporting Siren semantics
+  features:
+    - entity rendering (properties, subentities)
+    - link traversal (rel-based navigation)
+    - action forms (HTTP method support)
+    - URI-based entity IDs (enables sidelining vs embedding)
+  rule: create "ai/rules/jiron-client.mdc"
+  command: create "ai/commands/jiron-component.md"
+}
+
+DualRenderViews {
+  purpose: SEO + agent-friendly page rendering
+  browser: standard HTML
+  agent: token-efficient Jiron at "path/page.jiron"
+  discovery: <link rel="alternate" type="application/jiron" href="...">
+  hint: HTML comment instructing agents to fetch .jiron variant
+  rule: create "ai/rules/dual-render.mdc"
+  command: create "ai/commands/dual-view.md"
+}
+
+JironAgent {
+  purpose: guide AI agents in browsing Jiron APIs
+  model: fetch root → discover links/actions → navigate → execute → repeat
+  requires: no predefined tool knowledge
+  rule: create "ai/rules/jiron-agent.mdc"
+}
+
+StreamingMiddleware {
+  purpose: portable streaming responses for AI/chat
+  file: "src/server/middleware/with-stream.js"
+  pattern: generator → ReadableStream → chunked HTTP
+  portability: Web Streams API only (no Node.js streams)
+}
+
+## Server Framework
+AIDD {
+  pattern: createRoute + asyncPipe (functional composition)
+  NOT: Express
+  middleware: ({ request, response }) => Promise<{ request, response }>
+  data: attach to response.locals
+}
+
+## Streaming
+WebStreamsAPI {
+  why: portability (no Vercel vendor lock-in)
+  primitives: ReadableStream, TransformStream, TextEncoderStream
+  pattern: generator → ReadableStream → chunked response
+  works: Node.js, Deno, Vercel, Netlify, AWS Lambda, Deno Deploy
+  avoid: Node.js-specific streams (fs.ReadStream, etc.)
+}
+
+## Constraints
+- Follow existing aidd patterns (see ai/rules/, ai/commands/, src/server/)
+- Use createRoute + asyncPipe, NOT Express
+- Streaming via Web Streams API only (no vendor lock-in)
+- TDD for any implementation code
+- Requirements use "Given X, should Y" format
+- Verify against: jiron spec, siren spec, existing codebase conventions
+
+## References
+- https://github.com/ericelliott/jiron
+- https://github.com/kevinswiber/siren
+- https://github.com/ericelliott/siren-resource (deprecated, pattern reference only)

tasks/jiron-support-epic-original-prompt.sudo

@@ -0,0 +1,81 @@
+# Original Prompt - Jiron Support
+
+Please create a /task to add Jiron support to the aidd framework.
+
+
+Jiron Support:
+
+Jiron server:
+- Given functional requirements in a task, the AI agent should build a Jiron API which satisfies those functional requirements. See https://github.com/ericelliott/jiron
+
+Jiron Client
+
+- Given a Jiron server API endpoint, dynamically build web components capable of interacting with the endpoint:
+  - support siren semantics: https://github.com/kevinswiber/siren
+    - note: siren is kindof a mapping of html to json, so we can represent entity IDs with html-style URIs to support linking resources to other resources, including side-lining, rather than embedding child objects, collections, etc.
+
+Related, maybe useful: https://github.com/ericelliott/siren-resource
+
+Why?
+
+- Token-friendly AI agent-browsable interaction support for apps
+- Alternate server-rendered view of app pages - we should add an ai/rules and ai/commands pair to create server-rendered views for SEO and agent navigation. For browsers: render HTML. For agents, allow them to get a token-efficient Jiron view of that same document tree by fetching path/pagename.jiron. create a link with a real that clearly identifies this as a token-effient view for agents. Should include and HTML comment with instructions to the agent to fetch the Jiron views, instead.
+
+Before beginning:
+  Improve this prompt. Expand only where clarity is needed. Remove unnecessary detail. Favor inference to reduce token use. Use SudoLang syntax where it increases precision or compression. Markdown is valid SudoLang. Reference the syntax here: https://github.com/paralleldrive/sudolang/blob/main/syntaxes/syntax-test.sudo
+  Verify all facts against supplied resources. Never hallucinate.
+
+Create four files next to the task document:
+
+"${fileName}-original-prompt.sudo"
+"${fileName}-enhanced-prompt.sudo"
+"${fileName}-questions.md"
+"${fileName}-roundtable.md"
+
+file "${fileName}-original-prompt.sudo":
+  content: the exact prompt as received
+
+file "${fileName}-enhanced-prompt.sudo":
+  content:
+    improved prompt with:
+      concise structure
+      explicit intent
+      minimal rules
+      heavy reliance on inference
+      verified contextual details
+      SudoLang syntax only where beneficial
+
+file "${fileName}-questions.md":
+  content:
+    section "Open questions":
+      list all questions that arise during task interpretation
+      for each question:
+        write the literal question
+        infer the most likely answer using supplied resources and reasoning
+        include the inferred answer inline
+    section "Panel answers":
+      include the top one or two answers selected by the ExpertPanel and RTC
+    section "Unresolved":
+      list any questions that cannot be efficiently inferred
+
+file "${fileName}-roundtable.md":
+  content:
+    ExpertPanel:
+      assemble a small panel of relevant experts
+      their purpose is to critique the task and examine all open questions
+      each provides a concise viewpoint and critiques the others
+      panel surfaces uncertainties and proposes candidate answers
+    RTC depth 10:
+      evaluate all proposed answers
+      select the top one or two insights
+    section "Panel recommendations":
+      include those selected insights
+      note: these insights must also appear in "${fileName}-questions.md" under "Panel answers"
+
+function ImprovePrompt() {
+  1. restate objectives with minimal words
+  2. compress complexity into simple actionable blocks
+  3. specify required artifacts with compact SudoLang interface patterns
+  4. verify assumptions using supplied resources
+  5. rewrite with maximum clarity and minimal token footprint
+}

tasks/jiron-support-epic-questions.md

@@ -0,0 +1,103 @@
+# Jiron Support - Questions
+
+## Open Questions
+
+### Q1: Should Jiron output pure HTML or HTML-in-JSON?
+
+**Inferred Answer**: Pure HTML using Jade/Pug templating. Per the Jiron spec, it combines "Siren + Jade = HTML output" - the output is valid HTML that browsers render directly while remaining machine-parseable through semantic class attributes (`.property`, `.entity`, `.action`).
+
+### Q2: How should the client discover entity relationships in Jiron responses?
+
+**Inferred Answer**: Through Siren's `rel` attributes on links and sub-entities. The Siren spec requires embedded link sub-entities to have `rel` (relationship to parent) and `href`. Embedded representations also require `rel`. Links use RFC 5988 relation types.
+
+### Q3: What distinguishes "sidelining" from "embedding" for entity references?
+
+**Inferred Answer**: Sidelining = link reference (embedded link sub-entity with just `rel` and `href`); Embedding = full inline representation (embedded representation with all properties). Sidelining reduces payload size and enables lazy loading. The prompt suggests using HTML-style URIs for entity IDs to support this pattern.
+
+### Q4: What file format should .jiron files use?
+
+**Inferred Answer**: HTML with Jiron's semantic class structure. Though served with a custom extension, content is HTML that browsers can render. Suggest MIME type `application/jiron` or `text/html; profile=jiron` for agent detection.
+
+### Q5: Should JironClient components be framework-agnostic?
+
+**Inferred Answer**: Yes, use native Web Components (Custom Elements). This aligns with "dynamically build web components" in the spec - no framework dependency, works in any environment, progressive enhancement friendly.
+
+### Q6: How should agents discover the .jiron alternative?
+
+**Inferred Answer**: Two mechanisms: (1) `<link rel="alternate" type="application/jiron" href="page.jiron">` in HTML head, and (2) HTML comment near document start instructing agents to fetch the .jiron variant for token efficiency.
+
+### Q7: What HTTP methods should Jiron actions support?
+
+**Inferred Answer**: All REST methods: GET, POST, PUT, DELETE, PATCH. Both Siren and Jiron specs explicitly list these. HTML forms only support GET/POST natively, but Jiron's programmatic consumption enables full method support.
+
+### Q8: Should the server rules generate actual implementation code or just API specifications?
+
+**Inferred Answer**: Both, progressively. The rule should guide agents to first design the API structure (entities, actions, links), then generate implementation code following TDD. Consistent with existing aidd patterns like form-csrf.md.
+
+### Q9: How does Jiron compare to MCP for agent API interactions?
+
+**Inferred Answer**: They represent fundamentally different paradigms:
+
+| MCP | Jiron |
+|-----|-------|
+| Tools predefined in manifests | Actions discovered in responses |
+| Agent needs tool definitions per API | Agent needs ONE browse capability for all APIs |
+| Server implements MCP protocol | Server serves semantic HTML |
+| Schema declared upfront | Fields embedded in action forms |
+| Static capabilities | Dynamic capabilities per state |
+
+Jiron could replace MCP for web API interactions. Instead of defining 50 tools, expose one Jiron root endpoint. The agent fetches, parses, discovers what's available, executes actions, and the response tells them what's next. This is how browsers work - no manifest of "all things you can do on a website."
+
+Key insight: MCP = explicit tool definitions. Jiron = self-describing APIs. For browsable web resources, Jiron eliminates the need for per-API tool implementations.
+
+---
+
+## Panel Answers
+
+### Top Insight #1: One Capability to Browse Any API
+
+Jiron replaces explicit tool definitions (MCP) with self-describing APIs. Agents need ONE generic browse capability to interact with ANY Jiron API. No per-API tool manifests, no upfront schemas. The API itself tells agents what's possible at each state. This is how browsers work - and it scales infinitely better than predefined tool sets. For web API interactions, Jiron could eliminate the need for MCP entirely.
+
+### Top Insight #2: Sidelining + Self-Describing Actions
+
+Token efficiency comes from two patterns working together: (1) sidelining - link references instead of embedded data, fetch on-demand; (2) self-describing actions - no separate tool schemas, fields embedded in action forms. Combined, these make Jiron both architecturally superior AND more token-efficient than MCP+JSON patterns.
+
+---
+
+## Unresolved
+
+### U1: Jade/Pug dependency or alternative?
+
+The Jiron spec references Jade syntax, but Jade is now Pug and may add unwanted dependencies. Need to decide: use Pug, use an alternative templating approach, or generate HTML directly. Requires implementation-time decision based on aidd's existing tooling preferences.
+
+### U2: Authentication/Authorization handling in Jiron views?
+
+How should .jiron endpoints handle auth? Should they mirror the HTML endpoint's auth requirements exactly, or have separate considerations for agent access? May need OAuth/API key patterns for agent consumption.
+
+### U3: Caching strategy for dual-render views?
+
+Should .html and .jiron variants share cache keys? Different TTLs? Need to consider CDN behavior and agent polling patterns.
+
+---
+
+## Resolved (from refinement)
+
+### R1: What server framework should Jiron use?
+
+**Answer**: AIDD's custom functional composition framework using `createRoute` + `asyncPipe`, NOT Express. Middleware signature: `({ request, response }) => Promise<{ request, response }>`. Data passed via `response.locals`.
+
+### R2: How should streaming work without Vercel vendor lock-in?
+
+**Answer**: Use Web Streams API exclusively (ReadableStream, TransformStream, TextEncoderStream). This is the portable standard that works across:
+- Node.js 18+
+- Deno
+- Vercel Edge Functions
+- Netlify Edge
+- AWS Lambda (with response streaming)
+- Cloudflare Workers
+
+Avoid Node.js-specific streams (fs.ReadStream, etc.) which don't work in edge runtimes. Pattern: generator function → ReadableStream → chunked HTTP response.
+
+Sources:
+- [How to stream data over HTTP using NextJS](https://dev.to/bsorrentino/how-to-stream-data-over-http-using-nextjs-1kmb)
+- [MDN ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)