Add agent.md execution contract

[charliecreates]

Adds the requested root-level agent.md execution contract from issue #4 so the repo has a single canonical guide for building IntentOS (Tambo as kernel, Gemini as planner).

Changes

• Added agent.md in the repo root with the mission, architecture, intent contract, demo flow, and non-goals.

Verification

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

• npm run lint currently fails on main due to an ESLint config/runtime error (no code changes in this PR touch lint config).

reviewChanges skipped: agent.md maintainability suggestions (schema extraction / mapping checklists / acceptance criteria) are out of scope for “add the requested doc”.

Closes #4

[charliecreates]

The new agent.md is clear and actionable, but the "Intent JSON Schema" section is mislabeled (it’s an example payload, not a schema) which can mislead implementation. The baseline contract also risks encouraging scope creep via a broad intent_type enum and lacks a structured place for per-component configuration, which may lead to ad-hoc fields later. Addressing these now will keep the contract deterministic and implementation-friendly for the demo.

Additional notes (1)

• Maintainability | agent.md:73-89
required_components is currently just a list of strings, but later sections imply there are component-specific configuration needs (e.g., timeline range, task list items, chart type). Without a place to put per-component config, implementations tend to grow ad-hoc fields outside the contract.

Summary of changes

Summary

Adds a new root-level documentation file agent.md that defines the execution contract for IntentOS.

What’s included

• Mission + non-negotiable principles (e.g., Intent > Screens, Chat as OS bus).
• High-level architecture diagram connecting Tambo → Gemini → structured intent → dynamic UI.
• A canonical intent JSON baseline (fields like intent_type, required_components, elicitation_schema, workflow_state).
• Clear agent task breakdown across intent understanding, elicitation, dynamic rendering, thread semantics, and MCP signaling.
• A single required demo flow (“Create a 30-day internship preparation plan”), plus success criteria and non-goals.

[charliecreates]

The doc says "Outputs valid JSON only" but the shown baseline is presented as a "JSON Schema" while actually being a sample object, not a JSON Schema (no type, properties, required, etc.). This mismatch will cause downstream ambiguity when someone tries to implement validators or prompt constraints based on it.

Suggestion

Rename the section to something like "Intent JSON Shape (Baseline)" or replace it with a real JSON Schema (draft 2020-12 or similar) and explicitly separate example payload vs schema. For example:

• ### Intent JSON Schema (validator)
• ### Example intent payload

Reply with "@CharlieHelps yes please" if you’d like me to add a commit that updates the headings and adds a minimal real JSON Schema + example payload split.

[charliecreates]

intent_type is defined as goal_planning | analysis | tracking | decision_support, but the rest of the document strongly centers on a single flagship workflow (the 30-day plan). Having a broad enum in the "CRITICAL" contract invites overbuilding and inconsistent routing logic early on.

Suggestion

Constrain the baseline contract to the one demo-critical intent type for now (e.g., internship_plan or goal_planning) and add a note like "Other intent types are future work". This keeps routing/rendering deterministic for the hackathon demo and reduces accidental scope creep.

Reply with "@CharlieHelps yes please" if you want me to add a commit narrowing the enum and adding a brief extensibility note.