atris 2.1.0 → 2.2.1

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

@@ -39,9 +39,9 @@ The agent will:
 0. (Optional) Explore with you conversationally (`atris brainstorm`)
 1. Show you an **atris visualization** (diagram of the plan)
 2. Wait for your approval
-3. Create `atris/features/[name]/idea.md` + `build.md`
+3. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md`
 4. Execute step by step
-5. Review and update docs (2-pass validation)
+5. Validate (fill in validate.md, harvest lessons if anything surprised you)
 
 💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
 

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

@@ -33,9 +33,9 @@ Then describe what you want to build. The agent will:
 0. (Optional) Explore with `atris brainstorm` if uncertain
 1. Show you a visualization
 2. Wait for approval
-3. Create `atris/features/[name]/idea.md` + `build.md`
+3. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md`
 4. Execute step by step
-5. Review and update docs (2-pass)
+5. Validate (fill in validate.md, harvest lessons if anything surprised you)
 
 Commands: `brainstorm` (optional) → `plan` → `do` → `review`
 
@@ -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

@@ -39,9 +39,9 @@ The agent will:
 0. (Optional) Explore with you conversationally (`atris brainstorm`)
 1. Show you an **atris visualization** (diagram of the plan)
 2. Wait for your approval
-3. Create `atris/features/[name]/idea.md` + `build.md`
+3. Create `atris/features/[name]/idea.md` + `build.md` + `validate.md`
 4. Execute step by step
-5. Review and update docs (2-pass validation)
+5. Validate (fill in validate.md, harvest lessons if anything surprised you)
 
 💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
 

package/atris/atris.md

@@ -91,9 +91,9 @@ Stage: PLAN → do → review   (capitalize current stage)
 plan → do → review
 ```
 
-- **PLAN** — ASCII visualization, get approval, NO code yet
-- **DO** — Execute step-by-step, update journal
-- **REVIEW** — Test, validate, clean up, delete completed tasks
+- **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`.
 
 ---
 
@@ -141,6 +141,7 @@ 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 |

package/atris/features/README.md

@@ -10,15 +10,18 @@ Each feature gets its own folder:
 
 ```
 atris/features/
-├── _templates/           # Templates for new features
-│   ├── idea.md.template  # Problem, solution, visualization
-│   └── build.md.template # Step-by-step build instructions
+├── _templates/               # Templates for new features
+│   ├── idea.md.template      # Problem, solution, visualization
+│   ├── build.md.template     # Step-by-step build instructions
+│   └── validate.md.template  # Proof it works (or didn't)
 ├── feature-name-1/
-│   ├── idea.md           # Why we're building this
-│   └── build.md          # How to build it
+│   ├── idea.md               # Why we're building this
+│   ├── build.md              # How to build it
+│   └── validate.md           # Proof it works
 └── feature-name-2/
     ├── idea.md
-    └── build.md
+    ├── build.md
+    └── validate.md
 ```
 
 ---
@@ -30,7 +33,7 @@ atris/features/
 Run `atris` or `atris plan` and describe what you want. The agent will:
 1. Show visualization
 2. Wait for approval
-3. Create the feature folder with idea.md + build.md
+3. Create the feature folder with idea.md + build.md + validate.md
 
 ### Manual
 
@@ -41,31 +44,33 @@ If you want to create a feature manually:
 mkdir atris/features/your-feature-name
 cp atris/features/_templates/idea.md.template atris/features/your-feature-name/idea.md
 cp atris/features/_templates/build.md.template atris/features/your-feature-name/build.md
+cp atris/features/_templates/validate.md.template atris/features/your-feature-name/validate.md
 
 # Fill in the templates
 # Edit idea.md (problem, solution, visualization)
 # Edit build.md (step-by-step implementation)
+# Edit validate.md (proof it works — filled by validator)
 ```
 
 ---
 
 ## Workflow
 
-**Navigator Agent:**
+**Navigator Agent (idea.md):**
 1. Shows visualization
 2. Gets approval
-3. Creates `idea.md` + `build.md`
+3. Creates `idea.md` + `build.md` + `validate.md` (from templates)
 4. Adds entry to this README
 
-**Executor Agent:**
+**Executor Agent (build.md):**
 1. Reads `build.md`
 2. Executes step by step
 3. Updates status as work progresses
 
-**Validator Agent:**
-1. Verifies build matches spec
-2. Runs tests
-3. Updates status to "complete"
+**Validator Agent (validate.md):**
+1. Fills in `validate.md` — runs every check, records pass/fail
+2. If all pass → status "complete", lessons learned to journal
+3. If any fail → status stays "in-progress", lessons learned to journal
 4. Updates MAP.md if needed
 
 ---
@@ -74,12 +79,33 @@ cp atris/features/_templates/build.md.template atris/features/your-feature-name/
 
 ### Active Features
 
-(No active features in development)
+#### audit-gaps
+Close remaining audit gaps from self-audit
+- **Files:** atris/team/*.md, atris/features/README.md
+- **Status:** complete
+- **Keywords:** audit, persona, cleanup
+- **What:** Add PERSONA.md reference to all 5 agent specs, clean up stale feature statuses
 
 ---
 
 ### Completed Features
 
+#### self-improving-loop
+Make Atris recursive — validate.md lessons feed back into the next idea.md
+- **Files:** atris/lessons.md (new), atris.md, atris/team/navigator.md, atris/team/validator.md, atris/MAP.md
+- **Status:** complete
+- **Keywords:** recursion, lessons, feedback-loop, self-improving, lessons.md
+- **What:** lessons.md accumulates validated learnings; navigator reads them before planning; validator harvests them after validating
+- **Completed:** 2026-02-09
+
+#### wire-the-loop
+Connect lessons.md and validate.md to every CLI command and doc that references them
+- **Files:** commands/init.js, commands/workflow.js, commands/status.js, bin/atris.js, GETTING_STARTED.md, README.md, atris/atris.md
+- **Status:** complete
+- **Keywords:** wiring, cli, docs, lessons, validate, init, plan, review, status
+- **What:** 8 surgical edits to wire lessons.md and validate.md into init, plan, review, status, docs, and spec
+- **Completed:** 2026-02-09
+
 #### brainstorm — v2.0.0
 Conversational exploration mode for uncertain ideas
 - **Files:** bin/atris.js, atris/atris.md, atris/PERSONA.md, GETTING_STARTED.md, README.md, atris/MAP.md

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,29 +9,60 @@ 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` |
-| autopilot | PRD-driven autonomous execution - loops until done | — |
-| 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` |
+| calendar | Google Calendar integration via AtrisOS | — |
+| drive | Google Drive + Sheets integration via AtrisOS | — |
+| 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 | - |
+| skill-improver | Audit and improve skills against Anthropic guide | — |
+
+## ClawHub (External Distribution)
+
+Skills we publish to OpenClaw's ClawHub marketplace. These have YAML frontmatter and are formatted for external agents.
+
+| Skill | Description | Status |
+|-------|-------------|--------|
+| clawhub/atris | Codebase intelligence — MAP.md navigation for any agent | Ready to publish |
+
+```bash
+# Publish to ClawHub
+clawhub publish atris/skills/clawhub/atris --slug atris --name "Atris" --version 1.0.0
+```
+
+## Managing Skills
+
+```bash
+atris skill list              # Show all skills with compliance status
+atris skill audit [name|--all]  # Validate against Anthropic skill guide
+atris skill fix [name|--all]    # Auto-fix common issues
+```
 
 ## 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. Run `atris skill audit [name]` to validate
+3. Create `atris/policies/[name].md` (optional)
+4. Install to your agent (see Integration above)
+5. For external distribution, put in `atris/skills/clawhub/[name]/`

package/atris/skills/atris/SKILL.md

@@ -1,6 +1,13 @@
 ---
 name: atris
 description: Atris workflow enforcement for repos using atris/ (MAP, TODO, journal, features, plan-do-review, anti-slop). Use when the user asks to follow the Atris system or mentions atris, MAP.md, TODO.md, journal/logs, features, plan/do/review, or anti-slop policies.
+version: 1.0.0
+tags:
+  - atris
+  - workflow
+  - memory
+  - navigation
+  - anti-slop
 ---
 
 # Atris Skill

package/atris/skills/autopilot/SKILL.md

@@ -1,6 +1,11 @@
 ---
-description: PRD-driven autonomous execution - give it a task, it loops until done
-triggers: [autopilot, autonomous, "get it done", "finish this", "ship it"]
+name: autopilot
+description: PRD-driven autonomous execution - give it a task, it loops until done Triggers on "autopilot", "autonomous", "get it done", "finish this", "ship it".
+version: 1.0.0
+tags:
+  - autopilot
+  - workflow
+  - automation
 ---
 
 # Autopilot Skill
@@ -41,7 +46,7 @@ Autonomous task execution. Plan → Do → Review loop until acceptance criteria
 │     │ REVIEW: Validator checks             │          │
 │     │   - Check acceptance criteria        │          │
 │     │   - If fail: [REVIEW_FAILED] reason  │          │
-│     │   - If pass: <promise>COMPLETE</promise>        │
+│     │   - If pass: [COMPLETE]        │
 │     └──────────────────────────────────────┘          │
 │                                                       │
 │  3. OUTPUT                                            │
@@ -83,7 +88,7 @@ atris autopilot "Add feature" --iterations=3 --verbose
 
 ## Stop Conditions
 
-1. `<promise>COMPLETE</promise>` — All acceptance criteria met
+1. `[COMPLETE]` — All acceptance criteria met
 2. Max iterations reached (default: 5)
 3. Error that can't be recovered
 

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

package/atris/skills/backend/SKILL.md

@@ -1,7 +1,12 @@
 ---
-name: atris-backend
+name: backend
 description: Backend architecture policy. Use when building APIs, services, data access, or any backend work. Prevents over-engineering.
+version: 1.0.0
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+tags:
+  - backend
+  - architecture
+  - anti-patterns
 ---
 
 # atris-backend