atris 2.0.21 → 2.2.0

package/AGENT.md

@@ -0,0 +1,35 @@
+# AGENT.md
+
+This file provides guidance to any coding agent (Claude Code, Cursor, Windsurf, etc) when working with code in this repository.
+
+## Using Atris (If atris/ folder exists)
+
+**You are in an Atris-managed project.**
+
+**FIRST:** Read `atris/PERSONA.md` and adopt that personality.
+
+**Then follow this workflow:**
+1. **Execute first, research only if needed** — Run commands/tools directly. Don't search docs first—see what happens, then investigate if it fails. Saves context.
+2. **Before any change:** Read `atris/MAP.md` to find relevant files/components
+3. **When starting a task:** Check `atris/TODO.md` for existing tasks or add new one
+4. **After completing task:** Delete task from TODO.md
+5. **If architecture changes:** Update `atris/MAP.md` with new structure
+6. **Follow agent workflow:** navigator (find) → executor (build) → validator (verify)
+
+**Key files:**
+- `atris/PERSONA.md` - How to communicate and work (READ THIS FIRST)
+- `atris/MAP.md` - Navigation guide (where is X?)
+- `atris/TODO.md` - Active tasks (delete when done)
+- `atris/team/*.md` - Agent specs for reference
+
+---
+
+**Quick Start:**
+1. Read PERSONA.md
+2. Run `atris activate` to load context (no login or agent selection required)
+3. Check TODO.md for current work
+4. Use `atris visualize` to see plans before building
+5. Use `atris autopilot` when you want the CLI to shepherd plan → do → review loops (optional)
+6. Use `atris brainstorm` to generate a concise conversation starter before handing ideas to coding agents (optional)
+
+Need to chat with Atris cloud agents? Set them up later with `atris agent`, then authenticate once via `atris login`, and finally run `atris chat`.

package/AGENTS.md

@@ -0,0 +1,46 @@
+# AGENTS.md — Universal Agent Instructions
+
+> Works with: Claude Code, Cursor, Codex, Windsurf, and any AI coding agent.
+
+## Quick Start
+
+```bash
+atris
+```
+
+Run this first. Follow the output.
+
+## Core Files
+
+| File | Purpose |
+|------|---------|
+| `atris/PERSONA.md` | Communication style (read first) |
+| `atris/TODO.md` | Current tasks |
+| `atris/MAP.md` | Navigation (where is X?) |
+
+## Workflow
+
+```
+PLAN  → atris plan   (break ideas into tasks)
+BUILD → atris do     (execute tasks)
+CHECK → atris review (verify + cleanup)
+```
+
+## Rules
+
+- [ ] 3-4 sentences max per response
+- [ ] Use ASCII visuals for planning
+- [ ] Check MAP.md before touching code
+- [ ] Claim tasks in TODO.md before working
+- [ ] Delete tasks when done
+
+## Anti-patterns
+
+- Don't explore codebase manually (use MAP.md)
+- Don't skip visualization step
+- Don't leave stale tasks
+- Don't write verbose docs
+
+---
+
+**Protocol:** See `atris/atris.md` for full spec.

package/GETTING_STARTED.md

@@ -12,7 +12,7 @@ atris/
 ├── atris.md (atrisDev protocol + specs)
 ├── CLAUDE.md (tells agents to follow atrisDev)
 ├── MAP.md (navigation - AI will generate)
-└── agent_team/ (agent specs)
+└── team/ (agent specs)
 ```
 
 ## Quick Start (2 Steps)
@@ -91,7 +91,7 @@ Your system's navigation guide. Contains:
 
 **Use it:** When you need to find something fast or onboard new people
 
-### agent_team/navigator.md
+### team/navigator.md
 Your "where is X?" expert. Ask it questions like:
 - "Where is the authentication logic?"
 - "Show me all API endpoints"
@@ -99,7 +99,7 @@ Your "where is X?" expert. Ask it questions like:
 
 Always cites MAP.md with exact file:line references.
 
-### agent_team/executor.md
+### team/executor.md
 Your task runner. Give it work like:
 - "Add authentication to the upload endpoint"
 - "Fix the bug in user registration"
@@ -107,7 +107,7 @@ Your task runner. Give it work like:
 
 Reads MAP.md, plans execution with file:line references, executes step-by-step.
 
-### agent_team/validator.md
+### team/validator.md
 Your quality gatekeeper. Runs after changes to:
 - Check for breaking changes
 - Update MAP.md if structure changed

package/PERSONA.md

@@ -28,6 +28,8 @@ This defines how Atris agents communicate, decide, and work.
 
 ## Core Workflow
 
+**Read before you act.** Before planning or building, read the relevant files. Understand the current state. Your first action in any new area is always reconnaissance — not execution.
+
 **Always ask for intent.** Clarify before acting.
 
 **Use ASCII visualization to confirm understanding:**
@@ -42,7 +44,9 @@ Then go 3-4 sentences one by one through each task.
 
 Once every task is confirmed, create a plan.
 
-**Process:** Complete tasks in order of high reward, low risk first.
+**If a task is too big, break it down.** One job per task. If you can't describe "done" in one sentence, decompose it. Small precise tasks compound into big results.
+
+**Process:** Complete tasks in order of high reward, low risk first. Explore first, execute after.
 
 Always aim to be efficient and Pareto (80/20).
 

package/README.md

@@ -44,17 +44,25 @@ Works with: Claude Code, Cursor, Windsurf, GitHub Copilot, any agent.
 ## Update
 
 ```bash
-npm update -g atris
-atris update
+atris upgrade     # Install latest from npm
+atris update      # Sync local files to new version
 ```
 
----
+## Skills
 
-## Latest Updates
+Atris includes agent-agnostic skills that work with Claude, Cursor, Codex, any LLM:
 
+| Skill | Purpose |
+|-------|---------|
+| atris | Workflow enforcement + plan/do/review |
+| autopilot | PRD-driven autonomous execution |
+| backend | Backend architecture anti-patterns |
+| design | Frontend aesthetics policy |
+| meta | Metacognition for agents |
+| writing | Essay process with approval gates |
 
-See [releases](https://github.com/atrislabs/atris.md/releases) for full changelog.
+Install to Codex: `cp -r atris/skills/[name] ~/.codex/skills/`
 
 ---
 
-**License:** MIT | **Repo:** [github.com/atrislabs/atris.md](https://github.com/atrislabs/atris.git)
+**License:** MIT | **Repo:** [github.com/atrislabs/atris](https://github.com/atrislabs/atris.git)

package/atris/AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md — atris_team
+
+Instructions for coding agents working inside this repository.
+
+## Workflow (Default)
+
+1. Read `atris/PERSONA.md` and follow it (anti-slop, 3–4 sentences, ASCII for planning).
+2. Run `atris activate` to load the current working context.
+3. Use `atris/MAP.md` for navigation (file:line refs) when present.
+4. Track work in `atris/TODO.md` (target state = 0).
+5. Preferred loop: `atris plan` → `atris do` → `atris review`.
+
+## Repo Layout
+
+- `bin/atris.js` — CLI entrypoint + routing + natural-language entry.
+- `commands/` — most command implementations.
+- `lib/` — journal/task/file helpers (`journal`, `file-ops`, `state-detection`).
+- `utils/` — auth/API/config/update-check and cloud execution helpers.
+- `atris.md` — master spec template copied into user projects.
+
+## Notes
+
+- `TODO.md` is the current task file; `TASK_CONTEXTS.md` is legacy (fallback only).
+- Feature templates live in `atris/features/_templates/`.
+

package/atris/GEMINI.md

@@ -12,6 +12,14 @@ atris atris.md
 
 This is the Atris boot sequence. Show the output to the user, then respond naturally.
 
+## MAPFIRST (Enforced)
+
+**Before ANY file search/grep:**
+1. READ `atris/MAP.md`
+2. Search for your keyword in MAP
+3. If found → go directly to file:line
+4. If not found → grep ONCE, then UPDATE MAP.md
+
 ## Setup
 
 - Read `atris/PERSONA.md` (tone + operating rules).

package/atris/GETTING_STARTED.md

@@ -12,7 +12,7 @@ atris/
 ├── atris.md (atrisDev protocol + specs)
 ├── CLAUDE.md (tells agents to follow atrisDev)
 ├── MAP.md (navigation - AI will generate)
-└── agent_team/ (agent specs)
+└── team/ (agent specs)
 ```
 
 ## Quick Start (2 Steps)
@@ -91,7 +91,7 @@ Your system's navigation guide. Contains:
 
 **Use it:** When you need to find something fast or onboard new people
 
-### agent_team/navigator.md
+### team/navigator.md
 Your "where is X?" expert. Ask it questions like:
 - "Where is the authentication logic?"
 - "Show me all API endpoints"
@@ -99,7 +99,7 @@ Your "where is X?" expert. Ask it questions like:
 
 Always cites MAP.md with exact file:line references.
 
-### agent_team/executor.md
+### team/executor.md
 Your task runner. Give it work like:
 - "Add authentication to the upload endpoint"
 - "Fix the bug in user registration"
@@ -107,7 +107,7 @@ Your task runner. Give it work like:
 
 Reads MAP.md, plans execution with file:line references, executes step-by-step.
 
-### agent_team/validator.md
+### team/validator.md
 Your quality gatekeeper. Runs after changes to:
 - Check for breaking changes
 - Update MAP.md if structure changed

package/atris/atris.md

@@ -11,7 +11,7 @@
 1. Load context (ONE time, remember for session):
    - `atris/logs/YYYY/YYYY-MM-DD.md` (today's journal)
    - `atris/MAP.md` (navigation overview)
-   - `atris/agent_team/*.md` (all agent specs)
+   - `atris/team/*.md` (all agent specs)
 
 2. Output this EXACT box:
 
@@ -108,7 +108,7 @@ plan → do → review
 
 `atris next` = auto-selects agent based on journal state
 
-Specs loaded at activate from `agent_team/*.md`
+Specs loaded at activate from `team/*.md`
 
 ---
 
@@ -143,7 +143,7 @@ Specs loaded at activate from `agent_team/*.md`
 | `TODO.md` | Task queue (target: 0) |
 | `logs/YYYY/MM-DD.md` | Journal (daily) |
 | `PERSONA.md` | Communication style |
-| `agent_team/` | Agent behaviors |
+| `team/` | Agent behaviors |
 | `atrisDev.md` | Full spec (reference) |
 
 ---

package/atris/policies/LESSONS.md

@@ -10,3 +10,4 @@ Purpose: Capture short, actionable lessons after REVIEW misses.
 
 ## Entries
 - 2026-01-04 | meta | JSON edits break easily on quote boundaries → use Read tool to verify after Edit on .json files
+- 2026-01-28 | init | Meta-frameworks must be detected before base frameworks → Next.js check before React check (tests caught this)

package/atris/skills/README.md

@@ -9,28 +9,34 @@ Every process = **Skill + Policy**
 - `skills/[name]/SKILL.md` — How to DO (process)
 - `policies/[name].md` — How to REVIEW (validation)
 
-## Claude Integration
-
-Skills auto-detect via symlinks:
+## Integration
 
+### Claude Code
+```bash
+cd .claude/skills && ln -s ../../atris/skills/[name] [name]
 ```
-atris/skills/writing/SKILL.md     ← source of truth
-         ↑
-.claude/skills/writing/           ← symlink
+
+### Codex
+```bash
+cp -r atris/skills/[name] ~/.codex/skills/
 ```
 
 ## Available Skills
 
 | Skill | Description | Policy |
 |-------|-------------|--------|
-| atris | Atris workflow enforcement + plan/do/review | `policies/ANTISLOP.md` |
-| meta | Metacognition for agents - how to think about thinking | `policies/LESSONS.md` |
-| design | Frontend aesthetics - avoid generic AI look | `policies/atris-design.md` |
-| backend | Backend architecture - prevent over-engineering | `policies/atris-backend.md` |
-| writing | Essay process with approval gates | `policies/writing.md` |
+| atris | Workflow enforcement + plan/do/review | `policies/ANTISLOP.md` |
+| autopilot | PRD-driven autonomous execution | — |
+| backend | Backend architecture anti-patterns | `policies/atris-backend.md` |
+| design | Frontend aesthetics policy | `policies/atris-design.md` |
+| email-agent | Gmail integration via AtrisOS | — |
+| memory | Context and memory management | — |
+| meta | Metacognition for agents | `policies/LESSONS.md` |
+| writing | Essay process with gates | `policies/writing.md` |
+| copy-editor | Detects and fixes AI writing patterns | - |
 
 ## Creating Skills
 
 1. Create `atris/skills/[name]/SKILL.md`
-2. Create `atris/policies/[name].md`
-3. Symlink: `cd .claude/skills && ln -s ../../atris/skills/[name] [name]`
+2. Create `atris/policies/[name].md` (optional)
+3. Install to your agent (see Integration above)

package/atris/skills/autopilot/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: autopilot
+description: PRD-driven autonomous execution - give it a task, it loops until done
+triggers: [autopilot, autonomous, "get it done", "finish this", "ship it"]
+---
+
+# Autopilot Skill
+
+Autonomous task execution. Plan → Do → Review loop until acceptance criteria pass.
+
+## When to Use
+
+- User says "get this done" or "ship it"
+- User describes a feature/bug and wants hands-off execution
+- Any task that can be validated with acceptance criteria
+
+## Process
+
+```
+┌───────────────────────────────────────────────────────┐
+│  INPUT: "Add dark mode toggle"                        │
+│                                                       │
+│  1. GENERATE PRD                                      │
+│     - Type: feature or bug (auto-detect)              │
+│     - Acceptance criteria (testable conditions)       │
+│     - Priority: 1 (single story)                      │
+│                                                       │
+│  2. LOOP (max 5 iterations)                           │
+│     ┌──────────────────────────────────────┐          │
+│     │ PLAN: Navigator creates tasks        │          │
+│     │   - Read MAP.md for file locations   │          │
+│     │   - ASCII diagram of approach        │          │
+│     │   - Add tasks to TODO.md             │          │
+│     │   - Signal: [PLAN_COMPLETE]          │          │
+│     ├──────────────────────────────────────┤          │
+│     │ DO: Executor builds                  │          │
+│     │   - Implement each task              │          │
+│     │   - Verify changes work              │          │
+│     │   - Commit changes                   │          │
+│     │   - Signal: [DO_COMPLETE]            │          │
+│     ├──────────────────────────────────────┤          │
+│     │ REVIEW: Validator checks             │          │
+│     │   - Check acceptance criteria        │          │
+│     │   - If fail: [REVIEW_FAILED] reason  │          │
+│     │   - If pass: <promise>COMPLETE</promise>        │
+│     └──────────────────────────────────────┘          │
+│                                                       │
+│  3. OUTPUT                                            │
+│     - prd.json: PRD with passes: true                 │
+│     - progress.txt: Execution log                     │
+│     - Journal: Completion logged                      │
+└───────────────────────────────────────────────────────┘
+```
+
+## Acceptance Criteria Templates
+
+**Feature:**
+- Feature implemented and working as described
+- Tests pass (if test suite exists)
+- Build passes
+- Code follows project patterns (check MAP.md)
+
+**Bug:**
+- Bug is fixed and no longer reproducible
+- Regression test added (if applicable)
+- Build passes
+- No new bugs introduced
+
+## Commands
+
+```bash
+# With description
+atris autopilot "Add dark mode toggle"
+
+# Bug fix
+atris autopilot --bug "Login fails on Safari"
+
+# From TODO.md backlog
+atris autopilot --from-todo
+
+# With options
+atris autopilot "Add feature" --iterations=3 --verbose
+```
+
+## Stop Conditions
+
+1. `<promise>COMPLETE</promise>` — All acceptance criteria met
+2. Max iterations reached (default: 5)
+3. Error that can't be recovered
+
+## Rules
+
+- ONE task at a time
+- Verify before marking passes: true
+- Minimal changes only
+- Check MAP.md before touching code
+- Log to journal when complete

package/atris/skills/autopilot/atris-autopilot.md

@@ -0,0 +1,71 @@
+---
+description: Start autonomous loop - plan/do/review until done
+arguments:
+  - name: task
+    description: What to build (e.g., "Add dark mode toggle")
+    required: true
+  - name: max-iterations
+    description: Max loops before stopping (default 10)
+    required: false
+---
+
+# Atris Autopilot
+
+You are entering **autonomous mode**. You will loop until the task is complete or max iterations reached.
+
+## Setup
+
+First, create the state file:
+
+```bash
+mkdir -p .claude
+cat > .claude/atris-autopilot.state.md << 'EOF'
+---
+iteration: 1
+max_iterations: $ARGUMENTS.max-iterations|default:10
+completion_promise: <promise>COMPLETE</promise>
+---
+
+$ARGUMENTS.task
+EOF
+```
+
+## Your Task
+
+**$ARGUMENTS.task**
+
+## Process
+
+Each iteration:
+1. **PLAN** — Read MAP.md, identify files, create approach
+2. **DO** — Implement ONE thing, commit changes
+3. **REVIEW** — Check acceptance criteria
+
+## Acceptance Criteria
+
+- Task implemented and working
+- Tests pass (if they exist)
+- Build passes
+- Code follows patterns in MAP.md
+
+## Rules
+
+- ONE thing per iteration (trust the loop)
+- Search MAP.md before grepping
+- Search codebase before assuming not implemented
+- Update TODO.md with progress
+- Log learnings to atris/logs/
+
+## Completion
+
+When ALL acceptance criteria pass, output exactly:
+
+```
+<promise>COMPLETE</promise>
+```
+
+This signals the stop hook to end the loop.
+
+## Start
+
+Read atris/MAP.md now. Then begin iteration 1.

package/atris/skills/autopilot/hooks/stop-hook.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# Atris Autopilot Stop Hook
+# Catches exit, re-injects with MAP/TODO context
+
+STATE_FILE=".claude/atris-autopilot.state.md"
+
+# Read stdin JSON for transcript path
+INPUT=$(cat)
+TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')
+
+# Prevent infinite loops
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# No state file = not in autopilot mode
+if [ ! -f "$STATE_FILE" ]; then
+  exit 0
+fi
+
+# Parse state from YAML frontmatter
+iteration=$(grep "^iteration:" "$STATE_FILE" | cut -d' ' -f2)
+max_iterations=$(grep "^max_iterations:" "$STATE_FILE" | cut -d' ' -f2)
+
+# Validate numbers
+if ! [[ "$iteration" =~ ^[0-9]+$ ]] || ! [[ "$max_iterations" =~ ^[0-9]+$ ]]; then
+  echo '{"decision": "block", "reason": "Error: Invalid state file. Run /cancel-autopilot and restart."}'
+  exit 0
+fi
+
+# Max iterations reached - allow exit
+if [ "$iteration" -ge "$max_iterations" ]; then
+  rm -f "$STATE_FILE"
+  exit 0
+fi
+
+# Check transcript for completion promise
+if [ -n "$TRANSCRIPT_PATH" ] && [ -f "$TRANSCRIPT_PATH" ]; then
+  if grep -q "<promise>COMPLETE</promise>" "$TRANSCRIPT_PATH"; then
+    rm -f "$STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Increment iteration
+new_iteration=$((iteration + 1))
+sed -i.bak "s/^iteration:.*/iteration: $new_iteration/" "$STATE_FILE"
+rm -f "${STATE_FILE}.bak"
+
+# Extract original prompt
+prompt=$(sed -n '/^---$/,/^---$/!p' "$STATE_FILE" | tail -n +2)
+
+# Load context
+map_context=""
+[ -f "atris/MAP.md" ] && map_context=$(head -200 atris/MAP.md)
+
+todo_context=""
+[ -f "atris/TODO.md" ] && todo_context=$(cat atris/TODO.md)
+
+# Build reason (this is what Claude sees)
+reason="[AUTOPILOT ITERATION $new_iteration/$max_iterations]
+
+TASK: $prompt
+
+CONTEXT:
+- MAP.md loaded (use for navigation)
+- TODO.md loaded (track progress)
+
+RULES:
+- ONE thing this iteration
+- Search before assuming not implemented
+- When ALL done: output <promise>COMPLETE</promise>
+
+Continue working."
+
+# Block exit, provide reason
+echo "{\"decision\": \"block\", \"reason\": $(echo "$reason" | jq -Rs .)}"
+exit 0