Task 2

[jjf2009]

Below is a production-grade agent.md you can drop into the root of the repo.
This is written as an execution contract for an autonomous AI engineer (or a future teammate) to build IntentOS correctly, using Tambo as the kernel and Gemini as the planner.

No fluff. No ambiguity. This is hackathon-optimized and judge-aligned.

---

agent.md

Project Codename: IntentOS
Category: Intent-Native Productivity System
Primary Stack: Next.js (App Router), Tambo SDK, Gemini 3
Execution Mode: Solo / Autonomous Agent Compatible

---

1. Mission Statement

You are building IntentOS, a next-generation productivity system where:

Users express goals in natural language, and the system dynamically renders interactive workflows instead of static screens.

This is not a chat app.
Chat is the control surface.
UI is a side-effect of intent reasoning.

Your objective is to ship a fully working, judge-ready demo that demonstrates this paradigm clearly within hackathon constraints.

---

2. Core Design Principles (Non-Negotiable)

1. Intent > Screens

   • No fixed dashboards
   • No static workflows
   • UI components appear only when required by intent

2. Chat as an OS Bus

   • All interaction flows through Tambo’s message system
   • Threads represent one intent lifecycle

3. Minimal Surface, Maximum Depth

   • One killer end-to-end demo flow
   • Avoid feature sprawl

4. Leverage Existing Tambo Primitives

   • Do not rebuild chat, editors, or orchestration logic
   • Compose, don’t replace

---

3. High-Level Architecture

User Input (Text / Voice / Files)
        ↓
Tambo Message Pipeline
        ↓
Gemini 3 (Intent Classification + Planning)
        ↓
Structured Intent JSON
        ↓
Elicitation (if needed)
        ↓
Dynamic Component Rendering
        ↓
Interactive Workflow Execution

---

4. Canonical Intent Contract (CRITICAL)

All intents must resolve into a structured object.

Intent JSON Schema (Baseline)

{
  "intent_id": "uuid",
  "intent_type": "goal_planning | analysis | tracking | decision_support",
  "summary": "string",
  "confidence": 0.0,
  "required_components": [
    "elicitation",
    "timeline",
    "task_list",
    "chart"
  ],
  "elicitation_schema": {
    "fields": [
      {
        "key": "time_horizon",
        "type": "string",
        "required": true
      }
    ]
  },
  "workflow_state": "draft | active | completed"
}

This schema is the bridge between Gemini and Tambo UI rendering.

---

5. Agent Responsibilities (Task Breakdown)

A. Intent Understanding Layer (Gemini)

Objective: Convert free-form user input into structured intent.

Tasks:

• Write a system prompt for Gemini that:

  • Classifies intent
  • Determines missing information
  • Outputs valid JSON only

• Ensure deterministic structure

• Reject vague or multi-intent inputs with clarification requests

Deliverable:

• A single prompt file or inline system prompt
• Sample intent outputs stored for demo reliability

---

B. Elicitation Layer (Tambo Native)

Objective: Collect missing parameters before execution.

Use:

• ElicitationUI

Tasks:

• Dynamically render questions from elicitation_schema

• Support:

  • Single value fields
  • Multi-entry fields

• Lock intent once elicitation completes

Deliverable:

• Clean elicitation → execution transition
• No dead-ends or infinite loops

---

C. Dynamic Workflow Rendering

Objective: Render UI components based on intent needs.

Allowed Components:

• ElicitationUI
• DataCard
• Graph
• Markdown blocks with embedded components

Rules:

• No page navigation
• No hardcoded workflows
• Rendering must be driven by intent JSON

Deliverable:

• One flagship workflow fully implemented

---

D. Productivity Primitives

Implement only what supports the demo intent.

Examples:

• Task checklist with completion state
• Timeline visualization
• Progress or status indicator

State Handling:

• State may be local or ephemeral
• Persistence is optional, clarity is not

---

E. Thread & Memory Semantics

Use:

• ThreadHistory

Rules:

• One thread = one intent lifecycle
• Thread title = intent summary
• Thread history doubles as “intent archive”

---

F. MCP Integration (Signal, Not Depth)

Use:

• McpPromptButton
• McpResourceButton
• McpConfigModal

Tasks:

• Show MCP affordances
• Demonstrate at least one injected prompt or resource
• No real server required

Purpose:

• Signal extensibility
• Impress judges with forward compatibility

---

6. Non-Goals (Explicitly Out of Scope)

Do NOT implement:

• Authentication logic
• User settings
• Notifications
• Collaboration
• Theming systems
• Multi-intent orchestration

If it does not strengthen the intent → workflow story, it is a liability.

---

7. Demo Flow (Must Be Perfect)

Required Demo Scenario

“Create a 30-day internship preparation plan”

Steps:

1. User enters intent via chat or voice

2. Gemini returns structured intent

3. Elicitation collects missing constraints

4. System renders:

   • Timeline
   • Task checklist
   • Progress visualization

5. User interacts with tasks

6. System updates state and suggests next steps

This flow must be:

• Fast
• Visually clear
• Impossible to confuse with a normal chatbot

---

8. Judging Alignment Checklist

• Tambo Usage: Central, not decorative
• Generative UI: Clearly visible
• Innovation: Intent-native paradigm obvious in first 30 seconds
• Technical Execution: Clean, stable, explainable
• Narrative: “We design intent, not screens”

---

9. Success Criteria

The project is successful if:

• A judge can explain IntentOS after one demo
• The UI adapts visibly to user intent
• The system feels like infrastructure, not an app
• The codebase looks intentional, not hacked together

---

10. Final Instruction to Agent

Optimize for:

• Clarity over completeness
• Depth over breadth
• Systems thinking over UI polish

This is not a feature contest.
This is a category definition exercise.

Build accordingly.

[jjf2009]

@CharlieHelps can u do this ?

[charliecreates]

Expand this to see my work.

• Reviewed the repo layout and AGENTS.md to understand existing guidance for AI agents in this project and how CLAUDE.md is currently used.
• Confirmed that agent.md is not present anywhere in the repo by searching for references, so adding it would be a net-new convention rather than following an existing one.
• Checked recent merged PRs via the GitHub CLI to see how similar configuration or documentation files are introduced and documented in this repo.
• Created and switched to a dedicated working branch charlie/issue-4-add-agent-md off origin/main to isolate any upcoming changes related to issue #4.
• Added a new root-level agent.md file that defines IntentOS’s mission, non-negotiable design principles, and a high-level architecture diagram connecting user input, the Tambo message pipeline, Gemini 3, and dynamic workflow rendering.
• Documented a canonical Intent JSON schema in agent.md (including fields like intent_id, intent_type, required_components, elicitation_schema, and workflow_state) to serve as the bridge between Gemini and Tambo-driven UI.
• Expanded agent.md with detailed agent responsibilities across layers (Intent Understanding with a Gemini system prompt, Tambo-native ElicitationUI, dynamic component rendering, productivity primitives, ThreadHistory semantics, and MCP-related components such as McpPromptButton, McpResourceButton, and McpConfigModal).
• Spelled out non-goals and a required end-to-end demo scenario ("Create a 30-day internship preparation plan") plus judging criteria and success metrics so the file can act as an execution contract for any autonomous agent working on IntentOS.
• Pushed the charlie/issue-4-add-agent-md branch to GitHub and confirmed via git status that the working tree is clean and tracking origin/charlie/issue-4-add-agent-md.
• Opened a PR via gh pr create titled "Add agent.md execution contract" that adds the new agent.md, explains the scope and existing npm run lint failure in the PR body, and links it to close issue #4.

[charliecreates]

#4 (comment)

Yep — added the requested root-level agent.md execution contract in PR #5: #5

You can also view the file directly here: agent.md @ 1141137

Verification

# ESLint: FAILED (preexisting)
$ npm run lint
# TypeError: Converting circular structure to JSON

npm run lint is currently failing on main due to an ESLint config/runtime error; this PR only adds a Markdown file and doesn’t touch lint config.

[jjf2009]

@CharlieHelps
i need to to build the features meantioned the agent.md u have just made