atris 3.1.0 → 3.5.0

package/atris/atris.md

@@ -1,221 +1,190 @@
-# atris.md
+# atris
 
-> Drop this file anywhere. AI agent team activates.
+Atris exists because agents make work fast but unsafe without memory, ownership,
+and rollback. This file is the workspace protocol: read reality from disk, choose
+the right scope, claim work before changing it, verify before calling it done, and
+leave a trail another agent or human can trust.
 
----
-
-## ACTIVATE
+## activate
 
-**STOP. When you read this or hear "atris activate", do this immediately:**
+On session start, before responding:
 
-1. Load context (ONE time, remember for session):
-   - `atris/logs/YYYY/YYYY-MM-DD.md` (today's journal)
-   - `atris/MAP.md` (navigation overview)
-   - `atris/wiki/STATUS.md` (wiki health + next ingest targets, if present)
-   - `atris/team/*.md` (all agent specs)
+1. Read:
+   - `atris/logs/YYYY/YYYY-MM-DD.md` — today's journal
+   - `atris/MAP.md` — navigation
+   - `atris/wiki/STATUS.md` if present — current memory snapshot
 
-2. Output this EXACT box:
+2. Show this box, then ask what to work on if no task was already given.
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ ATRIS                                            [STAGE]    │
+│ atris                                              [stage]  │
 ├─────────────────────────────────────────────────────────────┤
-│ RECENT                                                      │
-│ • [2-3 items from Completed ✅]                             │
+│ recent                                                      │
+│ • [2-3 items from Completed]                                │
 ├─────────────────────────────────────────────────────────────┤
-│ NOW                                                         │
-│ ► [from In Progress 🔄] ····················· [in progress] │
+│ now                                                         │
+│ ► [from In Progress] ····················· [in progress]    │
 │   [from Backlog] ····························── [next]      │
 ├─────────────────────────────────────────────────────────────┤
-│ INBOX ([count])                                             │
-│ • [from Inbox section]                                      │
+│ inbox ([count])                                             │
+│ • [from Inbox]                                              │
 └─────────────────────────────────────────────────────────────┘
-
-Stage: PLAN → do → review   (capitalize current stage)
 ```
 
-3. Then ask: "What would you like to work on?"
-
-**DO NOT explain. DO NOT summarize. Output the box, then ask.**
-
----
+If a task was already given, show the box and proceed with that task.
 
-## NEXT
+## operating rules
 
-**STOP. When you hear "atris next", do this immediately:**
+You can move fast. You do not get to move blindly.
 
-1. Read today's journal
+Before changing anything, state:
+- the goal
+- the files or systems in scope
+- what "done" means
+- how it will be checked
+- what happens if it fails
 
-2. Check state and progress through stages:
+Then:
+- do not execute if another agent owns the same task or files
+- do not call something complete without verification
+- do not take irreversible actions without approval from the human
+- do not hide state outside markdown, logs, diffs, or the journal
+- do not edit the rules that judge you — the reward config, the authority policy, or this file
 
-   **No task in progress?**
-   - If Backlog has task → move to In Progress, stage = PLAN
-   - Else if Inbox has items → ask "Convert [item] to task?"
-   - Else → go to BRAINSTORM
+If you cannot honor these rules, stop, write why in the journal, and ask the human before continuing.
 
-   **Task in progress?** Progress to next stage:
-   - **PLAN** → Show ASCII plan, wait for approval → next stage = DO
-   - **DO** → Execute the work → next stage = REVIEW
-   - **REVIEW** → Run validator checks (test, verify, quality check)
-     - If passes → move to Completed, show DONE
-     - If fails → show issues, stay in DO
-
-3. Output this EXACT box:
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ NEXT: [task name]                              [PLAN|DO|REVIEW]
-│                                                             │
-│ [1-2 sentences: what you'll do in this stage]               │
-└─────────────────────────────────────────────────────────────┘
-```
+Labels used below:
+- `guarded` — checked by code or a pre-commit hook; bypassing is a bug
+- `expected` — convention; honor it or stop
 
-4. Wait for input. User says anything → execute current stage → update journal.
+## task shape
 
-5. After REVIEW passes, show:
+Every task in `TODO.md`:
 
 ```
-┌─────────────────────────────────────────────────────────────┐
-│ DONE: [task name]                                   [✓ REVIEWED] │
-│                                                             │
-│ [1-2 sentences: what was done + review result]              │
-└─────────────────────────────────────────────────────────────┘
+- **T#:** <title> [tier] [kind]
+  **Owner:** <slug>
+  **Files:** <paths touched>
+  **Exit:** <observable done condition>
+  **Verify:** <shell command, exits 0 on success>
+  **After:** <T# deps or none>
+  **Rollback:** <commit/checkpoint or "none (gray)">
 ```
 
-**Every task goes through PLAN → DO → REVIEW. No shortcuts.**
+| Field | Meaning | Enforcement |
+|---|---|---|
+| tier | `agent` proceeds, `gray` queues for approval, `human` never attempted by you | guarded |
+| kind | `explore` for ambiguous, `execute` for precise | expected |
+| Files | declared upfront; becomes the file lock | guarded (Swarlo claim) |
+| Verify | must exit 0 for the task to be complete | guarded (tick halts if missing) |
+| Rollback | how to undo; `git revert <sha>` for most tasks | expected |
 
----
+Deeper project work uses `atris/features/<slug>/` with `idea.md` (plan), `build.md` (steps), `validate.md` (checks). The task points at the triptych; the triptych holds the long form.
 
-## WORKFLOW
+Verify cannot be a raw shell shortcut; it must call a rubric or test that can fail before the work is done. Prefer `atris verify <slug> --section <name>`, which extracts the fenced bash under `## <name>` in `validate.md` and runs it. The rubric is read-only, deterministic, and references only the working tree.
 
-```
-scout → plan → do → review
-```
+## routing
 
-- **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
+Before picking up work, decide scope:
+- single project → route to that project's `atris/team/` and `TODO.md`
+- crosses projects → route to `atris/team/cross-project-architect/` and plan the dependency order first
 
----
-
-## TASK RULES
-
-Every task must follow these rules. No exceptions.
+The human is the constructor. You multiply. Handoff fidelity lives in the files, not in context.
 
-**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.
+## next
 
-**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."
+Move one task at a time through plan → do → review.
 
-**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.
+- **plan** — read relevant files, produce an ASCII visualization, wait for approval. No code.
+- **plan-review** — the validator reads the plan fresh and signs off with `SIGNOFF:` or halts with `REJECT:\nFIX:`. Plan does not move to do without signoff. Codex is optional escalation when `ATRIS_USE_CODEX=1` or the task carries `[codex]`.
+- **do** — claim the task (move it to In Progress with `Claimed by:` and a timestamp), execute step by step, update `MAP.md` and the journal as reality changes.
+- **review** — run the task's `Verify:` command, read the diff, run the relevant tests, append a one-line lesson to `lessons.md`, move the task to Completed.
 
-**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.
-
----
-
-## AGENTS
-
-| Command | Agent | Guardrail |
-|---------|-------|-----------|
-| `atris plan` | navigator | Plans only, NO code |
-| `atris do` | executor | Builds only, NO unplanned work |
-| `atris review` | validator | Checks only, NO new features |
-| `atris brainstorm` | brainstormer | Ideas only, NO code |
-
-`atris next` = auto-selects agent based on journal state
-
-Specs loaded at activate from `team/*.md`
-
----
-
-## BRAINSTORM
-
-**When queue empty (no backlog, no inbox):**
+State the next stage:
 
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│ BRAINSTORM                                           [PLAN] │
-├─────────────────────────────────────────────────────────────┤
-│ [1 sentence: what this project is]                          │
-│                                                             │
-│ Ideas:                                                      │
-│ 1. [suggestion based on MAP.md]                             │
-│ 2. [suggestion based on journal patterns]                   │
-│ 3. [suggestion based on product gaps]                       │
-├─────────────────────────────────────────────────────────────┤
-│ Pick one, remix, or "something else"                        │
+│ next: [task]                                  [plan|do|review]
+│ [1-2 sentences on this stage]                               │
 └─────────────────────────────────────────────────────────────┘
 ```
 
-**NO extra reads. Use loaded context. 3 ideas max.**
+If the queue is empty, suggest three ideas from `MAP.md`, the journal, or product gaps. No extra reads. Three max.
 
----
-
-## INDEX
+## sweep
 
-| File | Purpose |
-|------|---------|
-| `MAP.md` | Where is X? (navigation) |
-| `TODO.md` | Task queue (target: 0) |
-| `logs/YYYY/MM-DD.md` | Journal (daily) |
-| `wiki/STATUS.md` | Local project memory health |
-| `wiki/index.md` | Local knowledge index |
-| `PERSONA.md` | Communication style |
-| `team/` | Agent behaviors |
-| `atrisDev.md` | Full spec (reference) |
+Periodically, and before closing an endgame, clean:
+- stale tasks (claimed >3 days, never finished)
+- broken `MAP.md` refs (auto-heal where possible, flag the rest)
+- stale wiki pages (source newer than `last_compiled`)
+- orphan pages (unlinked from anywhere)
+- empty placeholder sections
 
----
+`atris clean` runs this. `atris clean --dry-run` previews.
 
-## JOURNAL FORMAT
+## journal
 
 ```
-## Completed ✅
-- **C1:** Description [✓ REVIEWED]
+## Completed
+- **C1:** Description [reviewed]
 
-## In Progress 🔄
+## In Progress
 - **T1:** Description
-  **Stage:** PLAN | DO | REVIEW
-  **Claimed by:** [Name] at [Time]
+  **Stage:** plan | do | review
+  **Claimed by:** <agent> at <ISO timestamp>
 
 ## Backlog
 - **T2:** Description
 
 ## Inbox
 - **I1:** Description
+
+## Notes
+[timestamped lines — one per discovery, decision, or tick]
 ```
 
----
+Context is a cache. Disk is truth. Route discoveries as they happen:
 
-## PERSISTENCE
+| You discover... | Write to... |
+|---|---|
+| a code location | `MAP.md` (file:line) |
+| a new task | `TODO.md` |
+| a decision or tradeoff | journal `## Notes` |
+| something learned | `lessons.md` (one line) |
+| work finished | journal `## Completed` (C#) |
+| a source changed | re-check pages that reference it |
 
-Context window = cache. Disk = truth. Route discoveries as they happen.
+Do not batch. Nothing important should live only in memory.
 
-| 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     |
-| Durable project knowledge | wiki/               | page update + STATUS refresh |
-| Something learned   | lessons.md           | One-line lesson      |
-| Work finished       | Journal → Completed  | C#: description      |
+## failure smells
 
-Don't batch. Don't wait for session end. Nothing important should live only in-context.
+If you notice these, stop and flag — do not continue:
+- **loop** — the same suggestion fires tick after tick, nothing changes on disk
+- **drift** — `MAP.md` file:line refs no longer match the code
+- **stale task** — a backlog task references a file or symbol that no longer exists
+- **hidden side effect** — an action changed external state (email sent, money moved, deploy) without a queued approval
+- **unverifiable completion** — a task marked complete without a `Verify:` command that actually ran
 
----
+Each has real examples in `lessons.md`. Before nontrivial execution, read the relevant recent lessons.
+
+## upkeep
+
+Pages that summarize or reference other files declare their sources in YAML frontmatter:
+
+    ---
+    last_compiled: YYYY-MM-DD
+    sources:
+      - path/to/source1
+      - path/to/source2
+    ---
+
+If any source was modified after `last_compiled`, the page is stale. Re-read the sources, update the page, bump `last_compiled`.
 
-## RULES
+Compounding: when you answer a question that required synthesis across pages, file the answer back — as a new page or into an existing one. Explorations accumulate.
 
-- 3-4 sentences max
-- ASCII visualization before any plan
-- Check MAP.md before touching code
-- Update journal after completing work
-- Delete tasks when done (target: 0)
-- Persist as you go (see PERSISTENCE)
+Linting during review catches stale pages, orphans, contradictions, and concepts mentioned but missing their own page.
 
 ---
 
-*Full spec and setup instructions: atrisDev.md*
+*Canonical copy: workspace root `atris.md`. Project copies are distributed; `atris update` syncs them. Full spec: `atrisDev.md`.*

package/atris/skills/aeo/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: aeo
+description: "AI Engine Optimization — write content engineered to get cited by ChatGPT, Claude, and Gemini. Not SEO. Triggers on: aeo, AI engine, llm citation, get cited, write for ai."
+when_to_use: "Use when the user wants content that ranks in AI answers (not Google SERP). Examples: 'write an AEO page', 'get Pallet cited by ChatGPT', 'aeo for our recruiting page', 'make this quotable by LLMs'."
+version: 0.1.0
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+tags:
+  - writing
+  - aeo
+  - marketing
+---
+
+# AEO — AI Engine Optimization
+
+Write content that LLMs cite when a human asks them a question. Different objective than SEO, different rules than craft writing.
+
+## When to use this skill
+
+- User wants content that gets quoted by ChatGPT / Claude / Gemini
+- User mentions "AEO", "AI engine", "LLM citation", "get cited", "write for AI"
+- Content is for a brand, product, person, or category the customer wants to own in LLM answers
+
+**Not for:**
+- Essays or long-form craft writing → use `writing` skill
+- LinkedIn posts / launch posts → use `launch` or `linkedin-content`
+- Copy-editing existing text → use `copy-editor`
+
+## Architecture
+
+The skill is scaffolding. The product is the backend endpoint:
+
+```
+atris write aeo "<topic>"
+        ↓
+POST /api/business/{id}/workspaces/{ws}/aeo/draft
+        ↓
+reads entity graph from /workspace/atris/aeo/{entities,definitions,stats}.md
+        ↓
+writes draft to /workspace/atris/aeo/drafts/<slug>.md
+        ↓
+returns draft + self-score + credit cost
+```
+
+Entity graph lives in the **customer's EC2 workspace** (not agent_files, not DB). The customer's files ARE the brand's machine-readable self.
+
+## The 10 rules (enforced by the endpoint + skill self-check)
+
+1. **Front-load the claim.** LLMs quote sentence 1 of a paragraph. No throat-clearing.
+2. **Name entities explicitly.** "Pallet" not "a leading freight platform." Entity density is how LLMs disambiguate and cite.
+3. **Canonical definition.** One sentence owns `X is Y that does Z` for the category. Make it liftable.
+4. **Q&A scaffolding.** H2s in question form: "What is X?" "How does X work?" — matches the prompts LLMs actually get.
+5. **Declarative stats with sources.** "$2.3B market (McKinsey 2025)" beats "a growing market." Citable atoms.
+6. **Comparison tables.** LLMs love structured data. Build one per category claim.
+7. **Fresh dates visible.** "Updated 2026-04-17" at top. LLMs weight recency.
+8. **Counter-position.** "Unlike X, Y does Z." Sharpens the entity in the model's mind.
+9. **No hedging.** "May/might/could" kills citation rate. Write assertive.
+10. **Schema-ready.** If HTML target, emit FAQPage + Article + HowTo JSON-LD.
+
+## Process
+
+```
+READ entity graph → DRAFT → SELF-SCORE → WRITE to workspace → (phase 2: AUDIT)
+```
+
+1. **READ** — Pull `entities.md`, `definitions.md`, `stats.md` from customer workspace. If missing, create skeleton files first.
+2. **DRAFT** — Generate article applying all 10 rules. Topic + target queries + entity context → article.
+3. **SELF-SCORE** — Append a `## AEO Self-Check` section: each rule scored pass/fail with evidence.
+4. **WRITE** — Save to `/workspace/atris/aeo/drafts/<slug>.md`.
+5. **AUDIT** (phase 2) — Run target queries against 4 LLMs, measure whether article is cited, write results to `/workspace/atris/aeo/audits/<slug>-<date>.md`.
+
+## Entity graph layout (in customer workspace)
+
+```
+/workspace/atris/aeo/
+├── entities.md        # named entities (products, people, companies)
+├── definitions.md     # canonical "X is Y" sentences
+├── stats.md           # citable stats with sources
+├── config.yml         # target_queries, competitor_brands, target_url
+├── drafts/            # AEO articles (one per slug)
+└── audits/            # citation-audit results (phase 2)
+```
+
+## Commands
+
+```bash
+# Generate a draft (credit-metered)
+atris write aeo "<topic>" --workspace <name>
+
+# Init the entity graph (writes skeleton files)
+atris aeo init --workspace <name>
+
+# View current drafts
+atris ls workspace/atris/aeo/drafts --workspace <name>
+```
+
+## Credits
+
+| Action | Cost |
+|---|---|
+| Draft a page | ~5–20 credits (token-metered) |
+| Audit (phase 2) | ~20–50 credits |
+| Monthly loop (phase 2) | metered per run |
+
+## Rules (non-negotiable)
+
+- Draft writes to **customer workspace**, never to `agent_file_memory`. EC2 is the source of truth.
+- Self-score section is mandatory in every draft.
+- Never hedge in the body. Hedging kills citation rate.
+- Never fabricate stats. If a stat is uncited, flag it in self-check.
+- Entity graph skeleton auto-creates if missing — never fail on first run.
+
+## Related
+
+- Feature: `atris/features/aeo/idea.md`
+- Backend: `POST /api/business/{id}/workspaces/{ws}/aeo/draft`
+- Sister skill: `writing` (human-reader craft)
+- Sister skill: `copy-editor` (deslopper)

package/atris/skills/atris/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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
+version: 2.0.0
 tags:
   - atris
   - workflow
@@ -13,40 +13,64 @@ tags:
 # Atris Skill
 
 ## Scope
-- Use this skill in repos that contain `atris/` or when the user requests Atris flow.
+- Use in repos that contain `atris/`, or when the user invokes Atris flow.
 - If unsure, ask one question before acting.
 
-## Required context (load only what you need)
+## Required context
 - Read `atris/atris.md`, `atris/PERSONA.md`, `atris/MAP.md`, `atris/TODO.md`.
 - Read today's journal `atris/logs/YYYY/YYYY-MM-DD.md` when planning or executing.
-- Read `atris/features/README.md` and templates only when creating a feature.
+- Before nontrivial execution, scan the recent entries in `atris/lessons.md` — patterns repeat.
+- Read `atris/features/<slug>/` only when opening or closing a feature.
 
 ## MAP-first
 - Read `atris/MAP.md` before any search.
 - If MAP lacks the answer, run one search and update MAP.
 
-## Intent capture
-- Ask clarifying questions until intent is unambiguous.
-- Define success criteria and required artifacts before planning.
-- Provide ASCII visualization, wait for approval, then plan.
+## Operating rules (from atris.md)
+Before changing anything, state: goal, files in scope, what "done" means, how it will be checked, what happens if it fails.
+
+Do not:
+- execute if another agent owns the same task or files
+- mark complete without running the task's `Verify:` command
+- take irreversible actions without approval from the human
+- hide state outside markdown, logs, diffs, or the journal
+- edit the reward config, authority policy, or `atris.md` itself
+
+If you cannot honor these, stop, write why in the journal, and ask.
+
+## Task shape
+Every task in `TODO.md` declares:
+```
+**T#:** <title> [tier] [kind]
+  **Owner:** <slug>
+  **Files:** <paths touched>
+  **Exit:** <observable done condition>
+  **Verify:** <shell command, exits 0 on success>
+  **After:** <deps or none>
+  **Rollback:** <commit/checkpoint or "none (gray)">
+```
+Tier: `agent` proceeds, `gray` queues for approval, `human` never attempted.
 
 ## Workflow
-- If the user says "atris activate" or "atris next", follow `atris/atris.md` exactly.
-- Follow: plan -> do -> review.
-- Do not code during PLAN.
-- During DO, execute approved steps only.
-- During REVIEW, test/verify and reconcile with success criteria.
-
-## Artifacts
-- Claim tasks in `atris/TODO.md`, delete when done.
-- Update journal after each stage change and completion.
-- For features, create `atris/features/<name>/idea.md` and `build.md` from templates, and update `atris/features/README.md`.
-- Use `atris/features/_templates/validate.md.template` when a validation script is needed.
-
-## Policies (anti-slop)
-- Always enforce `atris/policies/ANTISLOP.md`.
-- Load only the relevant domain policy: `atris-design.md`, `atris-backend.md`, `writing.md`.
+Move one task through plan → do → review:
+- **plan** — read relevant files, ASCII visualization, wait for approval. No code.
+- **do** — claim the task (In Progress + `Claimed by: <agent> at <ISO>`), execute step by step, update `MAP.md` and the journal as reality changes.
+- **review** — run `Verify:`, read diff, run tests, append one-line lesson to `lessons.md`, move task to Completed.
+
+Deeper work uses `atris/features/<slug>/` with `idea.md` (plan), `build.md` (steps), `validate.md` (checks). The task points; the triptych holds the long form.
+
+## Failure smells
+If you see these, stop and flag:
+- **loop** — same suggestion tick after tick, nothing changes on disk
+- **drift** — MAP.md refs no longer match the code
+- **stale task** — references a file or symbol that no longer exists
+- **hidden side effect** — external state changed without a queued approval
+- **unverifiable completion** — marked complete without `Verify:` actually running
+
+## Policies
+- Enforce `atris/policies/ANTISLOP.md` always.
+- Load `atris-design.md`, `atris-backend.md`, or `writing.md` only when that domain is in scope.
+- For authority tiers, see `policies/AGENT_AUTHORITY.md`.
 
 ## Improvement loop
-- After REVIEW, if output missed intent or failed validation, add a one-line lesson to `atris/policies/LESSONS.md`.
-- Promote repeated lessons (2-3 times) into the relevant policy and prune old items.
+After review, if output missed intent or failed verification, append one line to `atris/lessons.md`. If a lesson repeats 2-3 times, promote it into the relevant policy and prune.

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

@@ -24,6 +24,7 @@ Spec: https://github.com/atrislabs/member
 ```
 team/<name>/
 ├── MEMBER.md       REQUIRED  Persona + role + permissions
+├── SOUL.md         REQUIRED  Identity, values, lessons — who the agent is
 ├── skills/         OPTIONAL  SKILL.md files (capabilities)
 │   └── <skill>/
 │       └── SKILL.md
@@ -50,14 +51,33 @@ Ask the user:
 ```
 team/<name>/
 ├── MEMBER.md
+├── SOUL.md
 ├── skills/
 ├── tools/
 └── context/
 ```
 
-Use kebab-case for the name. Create all four directories even if empty.
+Use kebab-case for the name. Create all directories even if empty.
 
-### Step 3: Write MEMBER.md
+### Step 3: Write SOUL.md
+
+SOUL.md defines who the agent *is* — not what it does (MEMBER.md) or how it communicates (PERSONA.md). Use the template at `atris/team/_template/SOUL.md`.
+
+Write five sections:
+
+**Beliefs** — 3-5 convictions that guide judgment when rules don't apply. Not rules — things the agent holds true.
+
+**Values** — 2-3 values ordered by priority. What the agent optimizes for in ambiguous situations.
+
+**Lessons** — Start empty. These get synthesized from the agent's journal entries over time. Not copied from elsewhere — earned from experience.
+
+**Edges** — Honest self-assessment. What this agent is strong at and what it tends to get wrong. This helps the agent (and other agents) calibrate trust.
+
+**Voice** — One sentence that captures how this agent thinks. The inner monologue, not the output style.
+
+The soul should be *specific to this agent*. Two agents with the same role but different souls should make different judgment calls in ambiguous moments.
+
+### Step 4: Write MEMBER.md
 
 Use this structure:
 
@@ -83,7 +103,7 @@ Below the frontmatter, write three sections:
 
 **Rules** — Hard constraints. What the member must always or never do. Keep it to 3-5 rules.
 
-### Step 4: Add permissions
+### Step 5: Add permissions
 
 Common permission patterns:
 
@@ -110,7 +130,7 @@ permissions:
 
 Permissions are declarations, not enforcement. They tell the agent what its boundaries are. The agent respects them because they're in its instructions.
 
-### Step 5: Add skills (optional)
+### Step 6: Add skills (optional)
 
 If the member needs specific capabilities, create SKILL.md files:
 
@@ -138,7 +158,7 @@ skills:
   - <skill-name>
 ```
 
-### Step 6: Add context (optional)
+### Step 7: Add context (optional)
 
 Drop markdown files into `context/` with domain knowledge the member needs:
 - Playbooks, SOPs, guidelines
@@ -165,7 +185,7 @@ Add to your project's CLAUDE.md (or AGENTS.md for Codex):
 ## Team
 
 This project uses MEMBER.md team members in `team/`.
-When activated as a specific member, read `team/<name>/MEMBER.md`.
+When activated as a specific member, read `team/<name>/MEMBER.md` and `team/<name>/SOUL.md`.
 ```
 
 ## Multi-Agent Usage
@@ -173,11 +193,11 @@ When activated as a specific member, read `team/<name>/MEMBER.md`.
 Activate different members for different tasks:
 
 ```
-"Act as the navigator. Read team/navigator/MEMBER.md and plan this feature."
-"Act as the validator. Read team/validator/MEMBER.md and review these changes."
+"Act as the navigator. Read team/navigator/MEMBER.md and team/navigator/SOUL.md and plan this feature."
+"Act as the validator. Read team/validator/MEMBER.md and team/validator/SOUL.md and review these changes."
 ```
 
-Each member gets its own persona, skills, permissions, and context.
+Each member gets its own soul, persona, skills, permissions, and context.
 
 ## Examples