atris 2.3.8 → 2.5.0

package/atris/AGENTS.md

@@ -21,5 +21,4 @@ Instructions for coding agents working inside this repository.
 ## Notes
 
 - `TODO.md` is the current task file; `TASK_CONTEXTS.md` is legacy (fallback only).
-- Feature templates live in `atris/features/_templates/`.
-
+- Feature templates live in `atris/features/_templates/` (`idea`, `build`, `validate`, optional `changelog`).

package/atris/atris.md

@@ -88,12 +88,31 @@ Stage: PLAN → do → review   (capitalize current stage)
 ## WORKFLOW
 
 ```
-plan → do → review
+scout → plan → do → review
 ```
 
-- **PLAN** — ASCII visualization, get approval, NO code yet. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md` for substantial work.
-- **DO** — Execute build.md step-by-step, update journal
-- **REVIEW** — Fill in validate.md, test, clean up. If anything surprised you, append to `atris/lessons.md`.
+- **SCOUT** — Read relevant files first. Understand before you act. Report what you found.
+- **PLAN** — ASCII visualization, get approval, NO code yet
+- **DO** — Execute step-by-step, update journal
+- **REVIEW** — Test, validate, clean up, delete completed tasks
+
+---
+
+## TASK RULES
+
+Every task must follow these rules. No exceptions.
+
+**One job per task.** If a task touches more than 2-3 files, break it down. If you can't describe "done" in one sentence, it's too big.
+
+**Clear exit condition.** Every task states what "done" looks like. Not "improve auth" — instead: "Add session check to upload handler. Done when: unauthenticated requests return 401 and test passes."
+
+**Tag every task:**
+- `[explore]` — Ambiguous. Needs reading, research, judgment. Output is understanding.
+- `[execute]` — Precise. Route is clear. Just do it. Output is code or artifact.
+
+**Explore before execute.** When starting a new area of work, the first tasks should be `[explore]`. Read the files. Map the space. Report what you found. Then plan `[execute]` tasks based on what you learned.
+
+**Sequence matters.** Order tasks so each one builds context for the next. Early tasks should teach you about the problem. Later tasks use that knowledge.
 
 ---
 
@@ -141,7 +160,6 @@ Specs loaded at activate from `team/*.md`
 |------|---------|
 | `MAP.md` | Where is X? (navigation) |
 | `TODO.md` | Task queue (target: 0) |
-| `lessons.md` | What we learned (append-only, read by navigator, written by validator) |
 | `logs/YYYY/MM-DD.md` | Journal (daily) |
 | `PERSONA.md` | Communication style |
 | `team/` | Agent behaviors |
@@ -169,6 +187,22 @@ Specs loaded at activate from `team/*.md`
 
 ---
 
+## PERSISTENCE
+
+Context window = cache. Disk = truth. Route discoveries as they happen.
+
+| You discover...     | Write to...          | Format               |
+|---------------------|----------------------|----------------------|
+| Code location       | MAP.md               | file:line reference  |
+| New task            | TODO.md              | Task + exit condition |
+| Decision / tradeoff | Journal → Notes      | Timestamped line     |
+| Something learned   | lessons.md           | One-line lesson      |
+| Work finished       | Journal → Completed  | C#: description      |
+
+Don't batch. Don't wait for session end. Nothing important should live only in-context.
+
+---
+
 ## RULES
 
 - 3-4 sentences max
@@ -176,7 +210,7 @@ Specs loaded at activate from `team/*.md`
 - Check MAP.md before touching code
 - Update journal after completing work
 - Delete tasks when done (target: 0)
-- **Grep before acting:** `grep -i "<keywords>" atris/logs/**/*.md` — surface relevant history first
+- Persist as you go (see PERSISTENCE)
 
 ---
 

package/atris/features/_templates/changelog.md.template

@@ -0,0 +1,11 @@
+# Changelog — [Feature Name]
+
+Use this file only when useful (customer-visible changes, bug fixes, regressions, release notes).
+
+## [YYYY-MM-DD]
+
+- type: feature | bug | refactor | security
+- summary: One-line description of what changed
+- gates: PASS | FAIL
+- ref: PR/commit/link
+- rollback: One-line rollback note

package/atris/skills/clawhub/chief-of-staff/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: chief-of-staff
+description: "Daily briefing agent that learns your patterns and gets better every morning. Requires member-runtime skill. Use when you want a personalized morning briefing, daily summary, or 'brief me'."
+version: 1.0.0
+tags:
+  - daily-briefing
+  - personal-assistant
+  - stateful
+  - productivity
+  - chief-of-staff
+---
+
+# Chief of Staff
+
+A MEMBER.md worker that runs on the member-runtime skill. Install both:
+
+```
+clawhub install member-runtime
+clawhub install chief-of-staff
+```
+
+Then say: "brief me" or "be my chief of staff"
+
+## What This Member Does
+
+Delivers a daily briefing covering your calendar, tasks, and relevant news. Gets better over time through a journal loop -- tracks what you engage with, what you skip, and adapts.
+
+- **Day 1:** Generic briefing. Calendar + tasks. Fine but forgettable.
+- **Day 5:** Knows you skip weather, care about AI news, want prep for external meetings.
+- **Day 30:** Knows your Monday sprint routine, your team, your reading habits. The briefing is yours.
+
+## Files Installed
+
+```
+team/chief-of-staff/
+  MEMBER.md                          # Persona and workflow
+  skills/daily-briefing/SKILL.md     # How to build the briefing
+  skills/pattern-learning/SKILL.md   # How to learn from each run
+  context/preferences.md             # Starting defaults
+```
+
+## How It Works
+
+1. The member-runtime skill finds and loads `team/chief-of-staff/MEMBER.md`
+2. It reads the persona -- an opinionated prioritizer, not a data dumper
+3. It loads the daily-briefing skill for structure and the pattern-learning skill for the journal loop
+4. It checks memory for past briefings and user preferences
+5. It delivers a briefing adapted to what you actually care about
+6. After delivery, it writes a journal entry recording what happened
+7. Tomorrow's briefing is better because of today's journal
+
+## The Journal Loop
+
+This is what makes chief-of-staff different from every other briefing skill:
+
+- After each briefing, the member writes what was delivered and how the user reacted
+- After 3 days of consistent behavior, it promotes a pattern to durable memory
+- Direct requests ("never include weather") are remembered immediately
+- The member reads all of this before building tomorrow's briefing
+
+No configuration needed. Preferences build up through use.
+
+## Source
+
+Format spec and full source: https://github.com/atrislabs/member

package/atris/skills/clawhub/member-runtime/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: member-runtime
+description: "Load and run MEMBER.md team members -- complete AI workers with persona, skills, tools, context, and a journal that learns over time. Use when you want to activate a team member, run 'be my chief of staff', or manage stateful AI workers."
+version: 1.0.0
+tags:
+  - ai-agents
+  - team-management
+  - stateful-skills
+  - member-format
+  - workflow
+---
+
+# Member Runtime
+
+This skill teaches you how to load and run MEMBER.md team members. A member is a skill that manages skills -- it bundles a persona, capabilities, tools, permissions, and a journal that gets smarter over time.
+
+Format spec: https://github.com/atrislabs/member
+
+## What is a MEMBER.md?
+
+A MEMBER.md is a directory (or single file) that defines a complete AI worker:
+
+```
+team/{name}/
+  MEMBER.md              # Who this worker is (persona, workflow, rules)
+  skills/                # What they can do (SKILL.md files)
+  context/               # What they know (domain knowledge)
+  tools/                 # What they use (API docs, configs)
+  journal/               # What they've learned (grows over time)
+```
+
+## How to Load a Member
+
+When the user activates a member (e.g., "be my chief of staff", "act as the sdr"), follow these steps:
+
+### 1. Find the member
+
+Look for the member definition in order:
+1. `team/{name}/MEMBER.md` (directory format)
+2. `team/{name}.md` (flat file format)
+
+If not found, tell the user: "Member '{name}' not found. Install one from ClawHub or create team/{name}/MEMBER.md."
+
+### 2. Parse the frontmatter
+
+Read the YAML frontmatter between `---` delimiters. Extract:
+- `name` -- the member's identifier
+- `role` -- their job title
+- `skills` -- list of capability names
+- `permissions` -- what they can and can't do
+- `tools` -- what external tools they need
+
+### 3. Load skills
+
+For each skill in the frontmatter `skills` list:
+1. Check `team/{name}/skills/{skill-name}/SKILL.md`
+2. If found, read it and incorporate the instructions
+3. If not found, treat it as an abstract capability (the member knows how to do this but has no local definition)
+
+### 4. Load context
+
+Read all markdown files in `team/{name}/context/`. These are domain knowledge the member references while working -- playbooks, reference docs, default preferences. Load them into your working context.
+
+### 5. Read the journal
+
+This is what makes members stateful. Before doing anything:
+
+1. Search memory for past entries from this member: `memory_search("{member-name} preferences patterns")`
+2. Read today's and yesterday's memory files for recent journal entries
+3. Read `MEMORY.md` for durable preferences this member has recorded
+
+If no journal entries exist (first run), proceed with defaults from `context/preferences.md`.
+
+### 6. Become the member
+
+Adopt the persona, workflow, and rules from the MEMBER.md body. You are now this member. Follow their workflow step by step. Respect their permissions -- if `can-send: false`, draft but don't send.
+
+### 7. Write the journal
+
+After completing the task, write a journal entry to `memory/YYYY-MM-DD.md`:
+
+```markdown
+## {member-name} - {date}
+
+**Task:** What was requested
+**Delivered:** What was produced
+**User reaction:** What the user engaged with, asked follow-up about, or ignored
+**Pattern:** Any emerging preference (e.g., "user prefers bullets over prose")
+```
+
+If a pattern has been consistent for 3+ days, promote it to `MEMORY.md` as a durable preference.
+
+## Permissions Enforcement
+
+The member's `permissions` field declares intent. Enforce it:
+
+- `can-*: false` -- Don't do this action. Draft instead and ask for approval.
+- `approval-required: [action]` -- Pause before this action and ask the user.
+- If no permissions are declared, default to asking before any external action (send, delete, schedule).
+
+## Multiple Members
+
+Users can install multiple members. Each has its own persona, skills, and journal entries in memory. When switching between members, load the new member's MEMBER.md fresh -- don't carry over the previous member's persona.
+
+To list installed members: scan `team/` for MEMBER.md files and flat .md files.
+
+## Installing Members
+
+Members are installed by placing their files in `team/`. This happens via:
+- `clawhub install {member-name}` -- from ClawHub marketplace
+- Manual creation -- user creates `team/{name}/MEMBER.md`
+- Copy from another project -- member directories are portable (zip and share)

package/atris/skills/create-app/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: create-app
+description: Build and deploy an Atris app from a natural language description. Use when users ask to create Atris apps, workflows, or chat apps with setup automation.
+version: 1.0.0
+tags:
+  - atris
+  - apps
+  - workflow
+  - automation
+---
+
+# Create App
+
+Build and deploy an Atris app from a natural language description.
+
+## When to Use
+
+User says something like:
+- "I want daily analytics from my Mixpanel"
+- "Make me a chat app for job screening"
+- "Set up a workflow that monitors my app reviews"
+- "Build an app that qualifies leads from a CSV"
+
+## What an App Is
+
+An app is a container: data in, agent processes, data out. Three independent parts:
+
+- **App** = the box (storage, API, schedule, auth)
+- **Skill** = the brain (what to do with the data)
+- **Member** = the operator (the agent that runs it)
+
+Not every app needs all three. A chat widget just needs config. An autonomous workflow needs all three.
+
+## Bootstrap
+
+Get the user's Atris API token:
+
+```bash
+TOKEN=$(node -e "console.log(require('$HOME/.atris/credentials.json').token)" 2>/dev/null)
+if [ -z "$TOKEN" ]; then
+  TOKEN=$(python3 -c "import json,os; print(json.load(open(os.path.expanduser('~/.atris/credentials.json')))['token'])" 2>/dev/null)
+fi
+if [ -z "$TOKEN" ]; then
+  echo "Not logged in. Run: atris login"
+  exit 1
+fi
+echo "Ready."
+```
+
+Base URL: `https://api.atris.ai`
+Auth header: `Authorization: Bearer $TOKEN`
+
+## Flow
+
+Adapt the flow based on what the user described. Skip steps that don't apply.
+
+### Step 0: Clarify Intent
+
+Before building anything, ask the user:
+
+1. **Personal or business?** — First check if the user has any businesses: `GET https://api.atris.ai/api/business` with their token. If empty, it's personal — don't ask, just proceed. If they have businesses, ask: "Is this just for you, or for [business name]?"
+2. **How does data get in?** — Schedule (daily pull), webhook (data pushed in), manual (you trigger it), email, or chat?
+3. **How should output reach you?** — Email, feed post, API (for a custom UI), or just stored for querying?
+4. **Any API keys needed?** — Does this connect to an external service (Mixpanel, GitHub, Stripe, etc)?
+
+Keep it conversational. Don't ask all 4 at once if the answer is obvious from context. A mood tracker is clearly personal, manual input, no API keys. A Mixpanel analytics app clearly needs an API key and a daily schedule.
+
+### Step 1: Create the App
+
+Ask the user for a name if they didn't already give one. Generate a slug (lowercase, hyphens, no spaces).
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "APP_NAME",
+    "description": "DESCRIPTION",
+    "instructions": "SYSTEM_PROMPT",
+    "share_token": "SLUG",
+    "app_type": "external",
+    "access_mode": "private",
+    "ui_template": "chat",
+    "config": {}
+  }'
+```
+
+Save the returned `id` as `APP_ID` and `share_token` as `SLUG`.
+
+**Decisions:**
+- `access_mode`: `"private"` for personal workflows, `"public"` for shared apps
+- `ui_template`: `"chat"` for conversational, omit for headless workflows
+- `instructions`: the system prompt if it's a chat app, or a description of purpose for workflows
+
+### Step 2: Store API Keys (if needed)
+
+Only if the workflow needs external API access (Mixpanel, GitHub, Stripe, etc).
+
+Ask the user for each key. Store one at a time:
+
+```bash
+curl -s -X PUT "https://api.atris.ai/api/apps/SLUG/secrets/KEY_NAME" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"value": "THE_SECRET_VALUE"}'
+```
+
+Never log or display the secret value after storing it.
+
+**Skip this step** if the app doesn't need external API keys (chat apps, simple forms).
+
+### Step 3: Create the Agent + Skill (if needed)
+
+For autonomous workflows, the app needs an agent with a skill that knows what to do.
+
+**3a. Create or pick an agent:**
+
+If the user already has an agent, use it. Otherwise create one:
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/agent/create" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "AGENT_NAME",
+    "instructions": "AGENT_INSTRUCTIONS",
+    "access_mode": "api"
+  }'
+```
+
+Save the returned `id` as `AGENT_ID`. If access_mode is "api", also save the `api_key` (shown once).
+
+**3b. Write the skill:**
+
+The skill is the logic. Write it as a markdown file that describes what the agent should do. Store it in the agent's file memory:
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/agent/AGENT_ID/files" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "name": "skills/APP_SLUG.md",
+    "content": "SKILL_CONTENT"
+  }'
+```
+
+The skill content should include:
+- What data to pull and how (API endpoints, auth patterns)
+- What analysis to run
+- What output to produce
+- Where to store results
+
+Example skill for Mixpanel analytics:
+```markdown
+# Mixpanel Analytics Skill
+
+Pull daily event data from Mixpanel, analyze user segments, report insights.
+
+## Steps
+1. Use MIXPANEL_API_KEY to call Mixpanel Export API
+2. Pull events from last 24 hours
+3. Segment users by: first-generation completion, paid conversion, feature usage
+4. Compare against previous day's data (read from app storage)
+5. Identify: what grew, what dropped, any anomalies
+6. Store results in app data (collection: "daily-analysis")
+7. Email summary to owner
+
+## Output Format
+- 3-5 bullet points of what changed
+- One recommendation
+- Raw numbers for verification
+```
+
+**3c. Add agent as app member:**
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/SLUG/members" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"agent_id": "AGENT_ID", "role": "operator"}'
+```
+
+**Skip this step** for chat apps that don't need an autonomous agent.
+
+### Step 4: Set Schedule (if needed)
+
+For apps that run on a schedule:
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/scheduled-tasks" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "agent_id": "AGENT_ID",
+    "task_type": "pulse",
+    "cron_expression": "0 8 * * *",
+    "enabled": true
+  }'
+```
+
+Common schedules:
+- `"0 8 * * *"` — daily at 8am UTC
+- `"0 */6 * * *"` — every 6 hours
+- `"0 9 * * 1"` — weekly Monday 9am UTC
+
+**Skip this step** for on-demand apps (manual trigger only) or chat apps.
+
+### Step 5: Test It
+
+Trigger the first run to verify everything works:
+
+```bash
+curl -s -X POST "https://api.atris.ai/api/apps/SLUG/trigger" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"trigger_type": "manual"}'
+```
+
+Check status:
+
+```bash
+curl -s "https://api.atris.ai/api/apps/SLUG/status" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+Check run result:
+
+```bash
+curl -s "https://api.atris.ai/api/apps/SLUG/runs?limit=1" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+If the run succeeded, show the user. If it failed, read the error and fix.
+
+### Step 6: Confirm
+
+Tell the user:
+- App name and slug
+- What it does
+- When it runs (schedule or manual)
+- Where output goes (email, API, feed)
+- How to check status: `GET /api/apps/SLUG/status`
+- How to query data: `GET /api/apps/SLUG/data`
+
+## App Runtime API Reference
+
+All endpoints use the app's `share_token` as `{slug}`.
+
+```
+POST   /api/apps/{slug}/trigger          — run the app now
+POST   /api/apps/{slug}/ingest           — push data in
+POST   /api/apps/{slug}/ingest/batch     — push multiple items
+GET    /api/apps/{slug}/data             — read stored data
+GET    /api/apps/{slug}/data/{collection} — read specific collection
+GET    /api/apps/{slug}/status           — health, last run, next run
+GET    /api/apps/{slug}/runs             — execution history
+GET    /api/apps/{slug}/runs/{run_id}    — single run details
+PUT    /api/apps/{slug}/secrets/{key}    — store an API key (owner only)
+GET    /api/apps/{slug}/secrets          — list key names (owner only)
+DELETE /api/apps/{slug}/secrets/{key}    — remove a key (owner only)
+POST   /api/apps/{slug}/members          — add agent operator
+GET    /api/apps/{slug}/members          — list members
+DELETE /api/apps/{slug}/members/{agent_id} — remove member
+```
+
+## Examples
+
+**"I want daily analytics from Mixpanel"**
+→ Steps 1-5. Private app, Mixpanel key stored, agent with analytics skill, daily schedule, email output.
+
+**"Make a chat app for screening candidates"**
+→ Steps 1 only. Public app, chat template, instructions define the interview flow. No agent, no schedule, no keys.
+
+**"Set up a webhook that collects app feedback"**
+→ Steps 1, 3. Private app, agent processes inbound data. No schedule (webhook-triggered). User posts to `/ingest`, agent analyzes on trigger.
+
+**"Qualify leads from a CSV"**
+→ Steps 1-3, 5. Private app, agent with qualification skill. Manual trigger (upload CSV via `/ingest/batch`, then `/trigger`). No schedule.