atris 1.9.6 → 2.0.2

package/GETTING_STARTED.md

@@ -35,12 +35,15 @@ In your coding agent (Claude Code, Cursor, Windsurf, etc.), just describe what y
 "Refactor the auth system to use OAuth"
 ```
 
-The agent will automatically:
+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 `docs/features/[name]/idea.md` + `build.md`
+3. Create `atris/features/[name]/idea.md` + `build.md`
 4. Execute step by step
-5. Review and update docs
+5. Review and update docs (2-pass validation)
+
+💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
 
 **Total time: Start building immediately**
 
@@ -54,7 +57,7 @@ You can also run:
 atris activate
 ```
 
-This shows today's journal, MAP.md, and TASK_CONTEXTS.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
+This shows today's journal, MAP.md, and TODO.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
 
 ## Try the autopilot loop (optional)
 
@@ -111,7 +114,7 @@ Your quality gatekeeper. Runs after changes to:
 - Run tests and type checks
 - Report risks
 
-### TASK_CONTEXTS.md
+### TODO.md
 Auto-generated task bank with:
 - Task complexity (Trivial → Epic)
 - Exact file:line references
@@ -132,7 +135,7 @@ Once the files are populated, you can interact with your agents:
 
 **Give tasks to the executor:**
 ```
-@executor add rate limiting to the API (see TASK_CONTEXTS.md T-005)
+@executor add rate limiting to the API (see TODO.md T-005)
 ```
 
 **Validate changes:**
@@ -156,7 +159,7 @@ This syncs your local `atris.md` and agent templates to the latest version. Re-r
 1. **Let your AI agent generate MAP.md** (Step 2 above if you haven't already)
 2. **Explore MAP.md** - Get familiar with your system's structure
 3. **Try the pre-built agents** - Ask navigator questions, run executor tasks
-4. **Pick a task** - Check TASK_CONTEXTS.md for quick wins
+4. **Pick a task** - Check TODO.md for quick wins
 
 ## Need Help?
 

package/PERSONA.md

@@ -60,7 +60,7 @@ Delete when done. Clean workspace = clear mind.
 
 ## Collaboration
 
-**Trust the system.** MAP.md is truth. TASK_CONTEXTS.md is current work.
+**Trust the system.** MAP.md is truth. TODO.md is current work (formerly `TODO.md`).
 
 Navigator finds, executor builds, validator verifies. Stay in your lane.
 
@@ -86,7 +86,7 @@ Mistakes are fine if you learn and fix quickly.
 
 ❌ Make assumptions without checking MAP.md
 
-❌ Leave TODOs scattered in code (put them in TASK_CONTEXTS.md)
+❌ Leave TODOs scattered in code (put them in TODO.md)
 
 ❌ Overthink simple problems
 

package/README.md

@@ -1,6 +1,6 @@
 # atrisDev
 
-High-quality AI development workflow. Works with any coding agent.
+A better way to build with your coding agents.
 
 ## For Coding Agents
 
@@ -30,11 +30,14 @@ atris         # Loads context, ready to build
 ```
 
 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 `docs/features/[name]/idea.md` + `build.md`
+3. Create `atris/features/[name]/idea.md` + `build.md`
 4. Execute step by step
-5. Review and update docs
+5. Review and update docs (2-pass)
+
+Commands: `brainstorm` (optional) → `plan` → `do` → `review`
 
 Works with: Claude Code, Cursor, Windsurf, GitHub Copilot, any agent.
 
@@ -49,10 +52,6 @@ atris update
 
 ## Latest Updates
 
-**v1.9.0** - Natural language interface. Just say what you want:
-- `atris` - Load context
-- `atris build dark mode` - Start building
-- `atris fix the auth bug` - Start debugging
 
 See [releases](https://github.com/atrislabs/atris.md/releases) for full changelog.
 

package/atris/GETTING_STARTED.md

@@ -1,6 +1,6 @@
-# Getting Started with ATRIS
+# Getting Started with atrisDev
 
-Welcome! ATRIS transforms your system (codebase, product, sales process, etc.) into an AI-navigable workspace in under 10 minutes.
+Welcome! atrisDev gives you a high-quality AI development workflow that works with any coding agent.
 
 ## What Just Happened?
 
@@ -9,50 +9,55 @@ You ran `atris init` and got this folder structure:
 ```
 atris/
 ├── GETTING_STARTED.md (you are here!)
-├── PERSONA.md (agent communication style)
-├── atris.md (instructions for your AI agent)
-├── MAP.md (AI generates from your codebase)
-├── TASK_CONTEXTS.md (AI generates from MAP)
-└── agent_team/
-    ├── navigator.md (pre-built template, ready to use)
-    ├── executor.md (pre-built template, ready to use)
-    └── validator.md (pre-built template, ready to use)
+├── atris.md (atrisDev protocol + specs)
+├── CLAUDE.md (tells agents to follow atrisDev)
+├── MAP.md (navigation - AI will generate)
+└── agent_team/ (agent specs)
 ```
 
-## Quick Start (3 Steps)
+## Quick Start (2 Steps)
 
-### Step 1: Open atris.md
-Open `atris/atris.md` in your editor. This file contains detailed instructions for your AI agent.
+### Step 1: Run atris
 
-### Step 2: Paste to Your AI Agent
-Copy the entire contents of `atris.md` and paste it to Claude Code, Cursor, Windsurf, or your favorite AI coding assistant with this prompt:
+```bash
+atris
+```
+
+This loads your workspace context and activates the atrisDev protocol.
+
+### Step 2: Describe what you want
+
+In your coding agent (Claude Code, Cursor, Windsurf, etc.), just describe what you want to build:
 
 ```
-Read atris.md. Generate MAP.md and TASK_CONTEXTS.md for this project.
+"I want to add dark mode to the settings page"
+"Build a CSV export feature for the dashboard"
+"Refactor the auth system to use OAuth"
 ```
 
-### Step 3: Watch the Magic
-Your AI agent will:
-- Scan your project and generate `MAP.md` (a navigation guide with file:line references)
-- Generate `TASK_CONTEXTS.md` with actionable tasks extracted from your system
-- Optionally inject project-specific context into the pre-built agent templates
+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`
+4. Execute step by step
+5. Review and update docs (2-pass validation)
+
+💡 Tip: Use `atris brainstorm` if you're exploring options. Use `atris plan` when ready to build.
 
-**Agent templates ship ready to use:**
-- **navigator.md** - Answers "where is X?" questions
-- **executor.md** - Executes tasks with full context
-- **validator.md** - Validates changes and updates docs
+**Total time: Start building immediately**
 
-**Total time: ~5 minutes**
+## The atrisDev Protocol
 
-## Load the context (no login required)
+When agents see `atris/CLAUDE.md`, they automatically follow the atrisDev workflow. No manual setup needed.
 
-At any point—before or after your AI agent runs—you can load the local context with:
+You can also run:
 
 ```bash
 atris activate
 ```
 
-This shows today's journal, MAP.md, and TASK_CONTEXTS.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
+This shows today's journal, MAP.md, and TODO.md so you can browse and take notes offline. Authentication and agent selection are only required when you want to use `atris chat` with Atris cloud agents.
 
 ## Try the autopilot loop (optional)
 
@@ -109,7 +114,7 @@ Your quality gatekeeper. Runs after changes to:
 - Run tests and type checks
 - Report risks
 
-### TASK_CONTEXTS.md
+### TODO.md
 Auto-generated task bank with:
 - Task complexity (Trivial → Epic)
 - Exact file:line references
@@ -130,7 +135,7 @@ Once the files are populated, you can interact with your agents:
 
 **Give tasks to the executor:**
 ```
-@executor add rate limiting to the API (see TASK_CONTEXTS.md T-005)
+@executor add rate limiting to the API (see TODO.md T-005)
 ```
 
 **Validate changes:**
@@ -154,7 +159,7 @@ This syncs your local `atris.md` and agent templates to the latest version. Re-r
 1. **Let your AI agent generate MAP.md** (Step 2 above if you haven't already)
 2. **Explore MAP.md** - Get familiar with your system's structure
 3. **Try the pre-built agents** - Ask navigator questions, run executor tasks
-4. **Pick a task** - Check TASK_CONTEXTS.md for quick wins
+4. **Pick a task** - Check TODO.md for quick wins
 
 ## Need Help?
 

package/atris/PERSONA.md

@@ -60,7 +60,7 @@ Delete when done. Clean workspace = clear mind.
 
 ## Collaboration
 
-**Trust the system.** MAP.md is truth. TASK_CONTEXTS.md is current work.
+**Trust the system.** MAP.md is truth. TODO.md is current work (formerly `TODO.md`).
 
 Navigator finds, executor builds, validator verifies. Stay in your lane.
 
@@ -86,7 +86,7 @@ Mistakes are fine if you learn and fix quickly.
 
 ❌ Make assumptions without checking MAP.md
 
-❌ Leave TODOs scattered in code (put them in TASK_CONTEXTS.md)
+❌ Leave TODOs scattered in code (put them in TODO.md)
 
 ❌ Overthink simple problems
 

package/atris/agent_team/navigator.md

@@ -11,8 +11,8 @@ When the human gives you an idea (messy, conversational, exploratory):
 1. **Extract intent** — What are they trying to build? Why?
 2. **Generate atris visualization** — Show them exactly what will happen (frontend boxes / backend flow / database tables)
 3. **Confirm** — "Is THIS what you meant?" (y/n)
-4. **Create idea.md** — Save their messy intent to `docs/features/[name]/idea.md`
-5. **Generate build.md** — Create technical spec in `docs/features/[name]/build.md`
+4. **Create idea.md** — Save their messy intent to `atris/features/[name]/idea.md`
+5. **Generate build.md** — Create technical spec in `atris/features/[name]/build.md`
 
 **DO NOT execute.** You plan. Executor builds.
 
@@ -93,7 +93,7 @@ tests:
 
 ## Rules
 
-1. **Check docs/features/README.md first** — See what features exist, avoid duplication
+1. **Check atris/features/README.md first** — See what features exist, avoid duplication
 2. **Check MAP.md** — Find exact file:line references for code
 3. **Visualization before build.md** — Human confirms visual before technical spec
 4. **Be precise** — Exact files, exact lines, exact changes
@@ -101,7 +101,7 @@ tests:
 6. **Free-flow works** — Even exploratory conversations go through this flow
 
 **Before creating new feature:**
-- Read docs/features/README.md
+- Read atris/features/README.md
 - Search keywords for similar features
 - If exists: extend it, don't duplicate
 - Show visualization: "Builds on X, new file Y"

package/atris/agent_team/validator.md

@@ -78,7 +78,7 @@ Before approving, think 3 times:
 
 1. **Always run tests** — Never approve without green tests
 2. **Update MAP.md** — If files moved or architecture changed
-3. **Update docs/features/README.md** — Add new feature entry with summary, files, keywords
+3. **Update atris/features/README.md** — Add new feature entry with summary, files, keywords
 4. **Check build.md** — Execution must match the spec exactly
 5. **Block if broken** — Better to stop than ship bugs
 6. **3-4 sentences** — Keep feedback tight, clear, actionable

package/atris/atris.md

@@ -2,7 +2,7 @@
 
 > **Drop this markdown file anywhere. Scaffold and operate an AI agent team.**
 
-This spec defines how to transform any system (codebase, product, sales process, research) into a self-documenting, AI-navigable workspace. Standard structure: `atris/` folder with MAP.md, agent_team/, and TASK_CONTEXTS.md.
+This spec defines how to transform any system (codebase, product, sales process, research) into a self-documenting, AI-navigable workspace. Standard structure: `atris/` folder with MAP.md, agent_team/, and TODO.md.
 
 **Workflow:** Daily logs → Navigator plans → Executor builds → Validator reviews.
 
@@ -36,7 +36,7 @@ This spec defines how to transform any system (codebase, product, sales process,
 
 4. **DO NOT include this:**
    - COMPLEX Architecture Flows unless specified (keep it simple to understand)
-   - TODOs/Improvements (those go in TASK_CONTEXTS.md)
+   - TODOs/Improvements (those go in TODO.md)
    - Project stats (unnecessary metadata)
 
 5. **Quality Checklist Before Outputting:**
@@ -116,7 +116,7 @@ ATRIS ships with pre-built agent templates in `/atris/agent_team/` (copied durin
   - Ignore type errors or test failures
   ```
 
-- **Knowledge Base:** MAP.md, TASK_CONTEXTS.md (generated), test suite, type definitions
+- **Knowledge Base:** MAP.md, TODO.md (generated), test suite, type definitions
 - **Success Metric:** Tasks completed 95% first-try with zero regressions
 
 ### Agent 3: **validator.md** (in `/atris/agent_team/`)
@@ -146,7 +146,7 @@ ATRIS ships with pre-built agent templates in `/atris/agent_team/` (copied durin
 
 ---
 
-## Phase 3: Task Context System (TASK_CONTEXTS.md in `/atris/`)
+## Phase 3: Task Context System (TODO.md in `/atris/`, formerly `TODO.md`)
 
 **Goal:** Automatic task extraction with exact file/component context, so agents never guess.
 
@@ -216,9 +216,9 @@ ATRIS ships with pre-built agent templates in `/atris/agent_team/` (copied durin
    - Include both quick wins (low-risk) and strategic work (high-impact)
    - Map all dependencies explicitly
 
-3. Output: `/atris/TASK_CONTEXTS.md` (maintains and evolves as system changes)
+3. Output: `/atris/TODO.md` (maintains and evolves as system changes)
 
-4. On each MAP.md update, regenerate TASK_CONTEXTS.md to reflect new state
+4. On each MAP.md update, regenerate TODO.md to reflect new state
 
 ---
 
@@ -233,7 +233,7 @@ ATRIS ships with pre-built agent templates in `/atris/agent_team/` (copied durin
 - ✅ `agent_team/executor.md` (pre-built template)
 - ✅ `agent_team/validator.md` (pre-built template)
 - ⏳ `MAP.md` (AI agent generates from codebase)
-- ⏳ `TASK_CONTEXTS.md` (AI agent generates from MAP)
+- ⏳ `TODO.md` (AI agent generates from MAP)
 
 **Agent Enhancement:**
 After MAP.md generation, agents receive project context injection (framework, key dirs, search patterns). This keeps base templates clean while adding project-specific accelerators.
@@ -263,7 +263,7 @@ After MAP.md generation, agents receive project context injection (framework, ke
 
 1. **Brain Dump** — Run `atris log`, type thoughts into `## Inbox` section (unfiltered, no structure required)
 
-2. **Navigator Reviews** — Processes inbox entries, identifies patterns, creates tasks in TASK_CONTEXTS.md with MAP.md context
+2. **Navigator Reviews** — Processes inbox entries, identifies patterns, creates tasks in TODO.md with MAP.md context
 
 3. **Executor Builds** — Takes task → ASCII visualization → get approval → build step-by-step → validate alignment
 
@@ -468,7 +468,7 @@ Enhanced sync logic with auto-pull and conflict resolution.
 
 ## Phase 5.2: atrisDev Protocol (Universal Workflow)
 
-**The atrisDev Protocol** is a universal workflow that any coding agent can follow to produce high-quality output. When agents follow this protocol, they build features systematically with human approval gates and proper documentation.
+**The atrisDev Protocol** is a universal workflow that any coding agent can follow to produce high-quality output. When agents follow this protocol, they build features systematically with human approval gates and proper documentation, using small, low-risk changes that compound over time.
 
 **This protocol works with ANY agent:** Claude Code, Cursor, Windsurf, GitHub Copilot, or any LLM-based coding assistant.
 
@@ -496,6 +496,14 @@ The agent executes this workflow:
 
 ### atrisDev Workflow Steps
 
+**0. (Optional) Explore the Idea**
+
+If requirements are unclear, use `atris brainstorm` (or a structured conversation) to explore the problem and possible approaches *before* committing to any plan:
+
+- Clarify the problem, constraints, and “what good looks like”.
+- Decide whether this should become a feature folder (`atris/features/[name]/`) or a small, direct TODO.
+- Capture the refined idea into `atris/features/[name]/idea.md` once it is clear enough.
+
 **1. Show atris Visualization**
 
 Before writing any code, the agent creates a visual diagram showing:
@@ -529,7 +537,7 @@ Agent **MUST NOT** proceed until the human confirms the plan is correct.
 
 **3. Create idea.md**
 
-Path: `docs/features/[feature-name]/idea.md`
+Path: `atris/features/[feature-name]/idea.md`
 
 Contents:
 - **Problem Statement** — What are we solving?
@@ -539,7 +547,7 @@ Contents:
 
 **4. Create build.md**
 
-Path: `docs/features/[feature-name]/build.md`
+Path: `atris/features/[feature-name]/build.md`
 
 Contents:
 - **Step-by-step Implementation Plan** — Ordered list of tasks
@@ -557,7 +565,7 @@ Contents:
 
 - Run all tests
 - Verify success criteria from idea.md
-- Update `docs/features/README.md` with new feature entry
+- Update `atris/features/README.md` with new feature entry
 - Add completion to journal: `## Completed ✅`
 
 ---
@@ -584,6 +592,65 @@ Contents:
 
 ---
 
+## Phase 5.3: Claude Code Integration
+
+Auto-inject ATRIS context into Claude Code sessions via skills and commands.
+
+### Slash Command Setup
+
+Create `.claude/commands/atris.md`:
+
+```markdown
+---
+description: Activate ATRIS context - loads TODO.md, journal, and persona
+allowed-tools: Read, Bash, Glob, Grep
+---
+
+# ATRIS Activate
+
+Load these files:
+1. @atris/PERSONA.md (communication style)
+2. @atris/TODO.md (current tasks)
+3. @atris/MAP.md (navigation)
+
+Workflow: plan → do → review
+Rules: 3-4 sentences max, ASCII visuals, check MAP.md first
+```
+
+### Skill Setup
+
+Create `.claude/skills/atris/SKILL.md`:
+
+```markdown
+---
+name: atris
+description: ATRIS workspace navigation. Use when user mentions atris, TODO, tasks, MAP.md, or asks "where is X?"
+allowed-tools: Read, Bash, Glob, Grep, Write, Edit
+---
+
+# ATRIS Skill
+
+Detect: Project has `atris/` folder with MAP.md, TODO.md, PERSONA.md
+
+Workflow: Navigator (plan) → Executor (build) → Validator (verify)
+
+Key behaviors:
+- Read PERSONA.md first (3-4 sentences, ASCII visuals)
+- Check MAP.md for file:line refs
+- Update TODO.md (claim tasks, delete when done)
+```
+
+### Checklist
+
+- [ ] Create `.claude/commands/` directory
+- [ ] Create `.claude/skills/atris/` directory
+- [ ] Add `atris.md` command file
+- [ ] Add `SKILL.md` skill file
+- [ ] Test with `/atris` in Claude Code
+- [ ] Verify skill triggers on "atris" or "tasks" mentions
+
+---
+
 ## Phase 6: Future Roadmap (Vision)
 
 **See [`ATRIS_NOTES.md`](./ATRIS_NOTES.md) for full roadmap. Preview:**
@@ -610,9 +677,9 @@ Contents:
 - [ ] **Install:** `npm install -g atris` (instant)
 - [ ] **Init:** `atris init` - creates atris/ with templates (instant)
 - [ ] **Phase 1:** AI agent generates MAP.md from codebase (5 min)
-- [ ] **Phase 3:** AI agent generates TASK_CONTEXTS.md from MAP (2 min)
+- [ ] **Phase 3:** AI agent generates TODO.md from MAP (2 min)
 - [ ] **Validate:** Test navigator/executor/validator workflows (1 min)
-- [ ] **Ongoing:** Run `atris sync` to get template updates
+- [ ] **Ongoing:** Run `atris update` to get template updates
 
 **Total time to full instrumentation: ~8 minutes**
 
@@ -631,11 +698,11 @@ atris init
 # Hand atris/atris.md to your AI agent with this prompt:
 # "Read atris/atris.md. Execute Phase 1-4 to scaffold this system."
 
-# Agent generates MAP.md, agent_team/, and TASK_CONTEXTS.md in atris/
+# Agent generates MAP.md, agent_team/, and TODO.md in atris/
 # Your system is now fully instrumented for AI collaboration
 
 # Keep atris.md updated
-atris sync
+atris update
 ```
 
 ---
@@ -643,7 +710,7 @@ atris sync
 **Status:** Production ready. Run `atris init` in any project to get:
 1. Pre-built agent templates (navigator, executor, validator)
 2. AI generates MAP.md from your codebase in <5 minutes
-3. AI generates TASK_CONTEXTS.md with exact file:line context
+3. AI generates TODO.md with exact file:line context
 4. Full workflow: activate → plan → build → validate
 
 *Install once. Init anywhere. AI agents have instant context. Codebase becomes fully instrumented for AI collaboration.*