Prepare for repo rename: ai -> architecture

Updated all internal references for the rename:
- CLAUDE.md: New purpose statement, updated structure, added manifesto info
- README.md: Updated title, clone URL, folder structure
- commands/retro.md: Changed flowmade-one/ai to flowmade-one/architecture

The actual Gitea rename should be done after merging this PR.

Closes #44

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

CLAUDE.md

@@ -1,20 +1,34 @@
-# Claude Code AI Workflow
+# Architecture
 
-This repository contains configurations, prompts, and tools to improve the Claude Code AI workflow.
+This repository is the organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.
 
 ## Setup
 
 ```bash
 # Clone and install symlinks
-git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
-cd ai
+git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
+cd architecture
 make install
 ```
 
+## What This Repo Contains
+
+| Component | Purpose |
+|-----------|---------|
+| `manifesto.md` | Organization vision, personas, beliefs, principles |
+| `learnings/` | Historical record and governance |
+| `commands/` | AI workflow entry points (/work-issue, /manifesto, etc.) |
+| `skills/` | Tool and practice knowledge |
+| `agents/` | Focused subtask handlers |
+| `settings.json` | Claude Code configuration |
+| `Makefile` | Install symlinks to ~/.claude/ |
+
 ## Project Structure
 
 ```
-ai/
+architecture/
+├── manifesto.md    # Organization vision and beliefs
+├── learnings/      # Captured learnings and governance
 ├── commands/       # Slash commands (/work-issue, /dashboard)
 ├── skills/         # Knowledge modules (auto-triggered)
 ├── agents/         # Focused subtask handlers (isolated context)
@@ -25,41 +39,28 @@ ai/
 
 All files symlink to `~/.claude/` via `make install`.
 
-## Architecture
+## Two Levels of Vision
 
-### Skills
-Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`.
+| Level | Document | Command | Purpose |
+|-------|----------|---------|---------|
+| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
+| Product | `vision.md` | `/vision` | Product-specific direction and goals |
 
-- **Purpose**: Encode best practices and tool knowledge
-- **Location**: `skills/<name>/SKILL.md`
-- **Usage**: Included in commands for context, auto-triggered by Claude Code
+See the manifesto for our identity, personas, and beliefs about AI-augmented development.
 
-Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues.
+## Available Commands
 
-### Commands
-User-facing entry points invoked with `/command-name`. Run in main conversation context.
-
-- **Purpose**: Orchestrate workflows with user interaction
-- **Location**: `commands/<name>.md`
-- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
-
-Commands reference skills for knowledge and optionally spawn agents for subtasks.
-
-### Agents
-Small, focused units that handle specific subtasks in isolated context.
-
-- **Purpose**: Complex subtasks that benefit from isolation
-- **Location**: `agents/<name>/agent.md`
-- **Usage**: Spawned via Task tool, return results to caller
-
-Good agent candidates:
-- Code review (analyze diff, report issues)
-- Content generation (write issue body, PR description)
-- Analysis tasks (categorize, prioritize, summarize)
-
-**When to use agents vs direct execution:**
-- Use agents when: task is self-contained, benefits from isolation, can run in parallel
-- Use direct execution when: task needs conversation history, requires user interaction mid-task
+| Command | Description |
+|---------|-------------|
+| `/manifesto` | View/manage organization manifesto |
+| `/vision` | View/manage product vision and milestones |
+| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
+| `/dashboard` | Show open issues and PRs |
+| `/review-pr <n>` | Review PR with diff and comments |
+| `/create-issue` | Create single or batch issues |
+| `/retro` | Capture learnings as issues for encoding |
+| `/plan-issues` | Break down features into issues |
+| `/groom` | Improve issue quality |
 
 ## Gitea Integration
 
@@ -73,19 +74,32 @@ tea logins add --name flowmade --url https://git.flowmade.one --token <your-toke
 # Create token at: https://git.flowmade.one/user/settings/applications
 ```
 
-## Available Commands
+## Architecture Components
 
-| Command | Description |
-|---------|-------------|
-| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
-| `/dashboard` | Show open issues and PRs |
-| `/review-pr <n>` | Review PR with diff and comments |
-| `/create-issue` | Create single or batch issues |
-| `/retro` | Capture learnings, create improvement issues |
-| `/vision` | View/manage product vision and milestones |
-| `/plan-issues` | Break down features into issues |
-| `/improve` | Identify gaps between vision and backlog |
+### Skills
+Knowledge modules that teach Claude how to do something.
 
-## Vision & Goals
+- **Purpose**: Encode best practices and tool knowledge
+- **Location**: `skills/<name>/SKILL.md`
+- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
 
-Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command.
+### Commands
+User-facing entry points invoked with `/command-name`.
+
+- **Purpose**: Orchestrate workflows with user interaction
+- **Location**: `commands/<name>.md`
+- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
+
+### Agents
+Focused units that handle specific subtasks in isolated context.
+
+- **Purpose**: Complex subtasks that benefit from isolation
+- **Location**: `agents/<name>/agent.md`
+- **Usage**: Spawned via Task tool, return results to caller
+
+### Learnings
+Captured insights from work, encoded into skills/commands/agents.
+
+- **Purpose**: Historical record + governance + continuous improvement
+- **Location**: `learnings/YYYY-MM-DD-title.md`
+- **Flow**: Retro → Issue → Encode into learning + system update

README.md

@@ -1,4 +1,6 @@
-# Claude Code AI Workflow
+# Architecture
+
+The organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.
 
 A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
 
@@ -53,8 +55,8 @@ The project is built around three composable component types:
 
 ```bash
 # Clone the repository
-git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
-cd ai
+git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
+cd architecture
 
 # Install symlinks to ~/.claude/
 make install
@@ -87,7 +89,9 @@ echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username
 ## Project Structure
 
 ```
-ai/
+architecture/
+├── manifesto.md        # Organization vision, personas, beliefs
+├── learnings/          # Captured learnings and governance
 ├── commands/           # Slash commands invoked by users
 │   ├── work-issue.md
 │   ├── dashboard.md

commands/retro.md

@@ -1,13 +1,22 @@
 ---
-description: Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.
+description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 argument-hint: [task-description]
 ---
 
 # Retrospective
 
-Capture learnings from completed AI-assisted work to improve the workflow and refine the product vision.
+Capture insights from completed work as issues on the architecture repo. Issues are later encoded into learnings and skills/commands/agents.
 
 @~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/gitea/SKILL.md
+
+## Flow
+
+```
+Retro (any repo) → Issue (architecture repo) → Encode: learning file + skill/command/agent
+```
+
+The retro creates the issue. Encoding happens when the issue is worked on.
 
 ## Process
 
@@ -18,75 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow and re
    - What worked well?
    - Any specific improvement ideas?
 
-3. **Analyze and categorize**: Group learnings into:
-   - **Prompt improvements**: Better instructions for commands/skills
-   - **Missing capabilities**: New commands or skills needed
-   - **Tool issues**: Problems with tea CLI, git, or other tools
-   - **Context gaps**: Missing documentation or skills
+3. **Identify insights**: For each insight, determine:
+   - **What was learned**: The specific insight
+   - **Where to encode it**: Which skill, command, or agent should change?
+   - **Governance impact**: What does this mean for how we work?
 
-4. **Connect to vision** (if `vision.md` exists in the target repo):
-   - Did this work make progress on any vision goals?
-   - Did learnings reveal new priorities that should become goals?
-   - Did we discover something that should be a non-goal?
-   - Should the current focus shift based on what we learned?
-
-   If any vision updates are needed:
-   - Present suggested changes to `vision.md`
-   - Ask for approval
-   - Update the vision file and sync to Gitea
-
-5. **Generate improvement issues**: For each actionable improvement:
-   - Determine the appropriate milestone (see Milestone Categorization below)
-   - Create an issue in the AI repo with the milestone assigned:
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
 
    ```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
+   tea issues create -r flowmade-one/architecture \
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]
+
+   ## Insight
+   [The specific learning - be concrete and actionable]
+
+   ## Suggested Encoding
+   - [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
+   - [ ] \`commands/xxx.md\` - [what to add/change]
+   - [ ] \`agents/xxx/agent.md\` - [what to add/change]
+
+   ## Governance
+   [What this means for how we work going forward]"
    ```
 
-## Milestone Assignment
+5. **Connect to vision**: Check if insight affects vision:
+   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
+   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
 
-Before creating issues, fetch available milestones:
+   If vision updates are needed, present suggested changes and ask for approval.
 
-```bash
-tea milestones -f title,description
-```
+## When the Issue is Worked On
 
-For each issue, automatically assign to the most relevant milestone by matching:
-- Issue content/problem area → Milestone title and description
-- If no clear match, ask the user which milestone (goal) the issue supports
-- If no milestones exist, skip milestone assignment
+When encoding a learning issue, the implementer should:
 
-## Issue Format
-
-Use this structure for retrospective issues:
+1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
 
    ```markdown
-## Context
-What task triggered this learning (brief).
+   # [Learning Title]
 
-## Problem / Observation
-What was the friction point or insight.
+   **Date**: YYYY-MM-DD
+   **Context**: [Task that triggered this learning]
+   **Issue**: #XX
 
-## Suggested Improvement
-Concrete, actionable change to make.
+   ## Learning
 
-## Affected Files
-- commands/xxx.md
-- skills/xxx/SKILL.md
+   [The specific insight]
+
+   ## Encoded In
+
+   - `skills/xxx/SKILL.md` - [what was added/changed]
+   - `commands/xxx.md` - [what was added/changed]
+
+   ## Governance
+
+   [What this means for how we work]
    ```
 
+2. **Update skill/command/agent** with the encoded knowledge
+
+3. **Close the issue** with reference to the learning file and changes made
+
+## Encoding Destinations
+
+| Insight Type | Encode In |
+|--------------|-----------|
+| How to use a tool | `skills/[tool]/SKILL.md` |
+| Workflow improvement | `commands/[command].md` |
+| Subtask behavior | `agents/[agent]/agent.md` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
 ## Labels
 
-Add appropriate labels:
-- `retrospective` - Always add this
+Add appropriate labels to issues:
+- `learning` - Always add this
 - `prompt-improvement` - For command/skill text changes
-- `new-feature` - For new commands/skills
+- `new-feature` - For new commands/skills/agents
 - `bug` - For things that are broken
 
 ## Guidelines
 
-- Be specific and actionable - vague issues won't get fixed
-- One issue per improvement (don't bundle unrelated things)
-- Reference specific commands/skills when relevant
-- Keep issues small and focused
-- Skip creating issues for one-off edge cases that won't recur
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
+- **Be specific**: Vague insights can't be encoded
+- **One issue per insight**: Don't bundle unrelated things
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur

commands/vision.md

@@ -8,47 +8,54 @@ argument-hint: [goals]
 @~/.claude/skills/vision-management/SKILL.md
 @~/.claude/skills/gitea/SKILL.md
 
+This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
+
 ## Architecture
 
-The vision system has two layers:
+| Level | Document | Purpose | Command |
+|-------|----------|---------|---------|
+| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
+| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
+| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
 
-| Layer | Purpose | Location |
-|-------|---------|----------|
-| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
-| **Milestones** | Goals with progress tracking | Gitea milestones |
-
-Issues are assigned to milestones. Progress is visible through milestone completion.
+Product vision inherits from and extends the organization manifesto.
 
 ## Process
 
-1. **Check for existing vision**: Look for `vision.md` in the current repo root.
+1. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context)
 
-2. **If no vision exists**:
-   - Ask the user if they want to create one
+2. **Check for product vision**: Look for `vision.md` in the current repo root
+
+3. **If no vision exists**:
+   - Reference the organization manifesto if it exists
+   - Ask if the user wants to create a product vision
    - Guide them through defining:
-     1. **Personas**: Who are we building for? (2-4 specific personas)
-     2. **Jobs to be done**: What are they trying to achieve?
-     3. **The problem**: What pain points exist today?
-     4. **The solution**: How does this product address their jobs?
-     5. **Guiding principles**: What beliefs guide decisions?
-     6. **Non-goals**: What are we explicitly NOT doing?
-   - Create `vision.md` (do NOT include goals/progress - that's milestones)
-   - Ask about initial goals tied to personas/jobs, create as Gitea milestones
+     1. **Product personas**: Who does this product serve? (may extend org personas)
+     2. **Product jobs**: What specific jobs does this product address?
+     3. **The problem**: What pain points does this product solve?
+     4. **The solution**: How does this product address those jobs?
+     5. **Product principles**: Any product-specific principles (beyond org principles)?
+     6. **Product non-goals**: What is this product explicitly NOT doing?
+   - Create `vision.md`
+   - Ask about initial goals, create as Gitea milestones
 
-3. **If vision exists**:
-   - Display the vision philosophy from `vision.md`
+4. **If vision exists**:
+   - Display organization context (if manifesto exists)
+   - Display the product vision from `vision.md`
    - Show current milestones and their progress: `tea milestones`
    - Check if `$1` specifies an action:
      - `goals`: Manage milestones (add, close, view progress)
    - If no action specified, just display the current state
 
-4. **Managing Goals (milestones)**:
+5. **Managing Goals (milestones)**:
    ```bash
    # List milestones with progress
    tea milestones
 
    # Create a new goal
-   tea milestones create --title "<goal>" --description "<success criteria>"
+   tea milestones create --title "<goal>" --description "For: <persona>
+Job: <job to be done>
+Success: <criteria>"
 
    # View issues in a milestone
    tea milestones issues <milestone-name>
@@ -60,37 +67,44 @@ Issues are assigned to milestones. Progress is visible through milestone complet
 ## Output Format
 
 ```
-## Who We Serve
+## Organization Context
 
-- **[Persona 1]**: [Brief description]
-- **[Persona 2]**: [Brief description]
+See manifesto for shared personas, beliefs, and principles.
+[Link or note about manifesto.md location]
 
-## What They're Trying to Achieve
+## Product: [Name]
 
-- "[Job to be done 1]"
-- "[Job to be done 2]"
+### Who This Product Serves
 
-## Vision
+- **[Persona 1]**: [Product-specific description]
+- **[Persona 2]**: [Product-specific description]
+
+### What They're Trying to Achieve
+
+- "[Product-specific job 1]"
+- "[Product-specific job 2]"
+
+### Product Vision
 
 [Summary of problem/solution from vision.md]
 
-## Goals (Milestones)
+### Goals (Milestones)
 
 | Goal | For | Progress | Due |
 |------|-----|----------|-----|
 | [title] | [Persona] | 3/5 issues | [date] |
 
-## Current Focus
+### Current Focus
 
 [Open milestones with nearest due dates or most activity]
 ```
 
 ## Guidelines
 
-- vision.md is the stable "why" and "who" document - update rarely
-- Personas and jobs to be done are foundational - everything traces back to them
-- Milestones are actionable goals - each should serve a specific persona's job
-- Assign issues to milestones to track progress
-- Use milestone descriptions for: persona, job, success criteria
-- Due dates on milestones are optional but help prioritization
-- If you can't tie work to a persona/job, question whether it should be done
+- Product vision builds on organization manifesto - don't duplicate, extend
+- Product personas can be more specific versions of org personas
+- Product jobs should trace back to org-level jobs to be done
+- Milestones are product-specific goals toward the vision
+- Use `/manifesto` for organization-level identity and beliefs
+- Use `/vision` for product-specific direction and goals
+- If this is the architecture repo itself, use `/manifesto` instead

skills/vision-management/SKILL.md

@@ -1,123 +1,175 @@
 ---
 name: vision-management
-description: Create, maintain, and evolve a product vision. Use when initializing a vision, updating goals, aligning work with vision, or connecting learnings to vision refinement.
+description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
 ---
 
 # Vision Management
 
-How to create, maintain, and evolve a product vision for continuous improvement.
+How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
 
 ## Architecture
 
-The vision system has two layers:
+| Level | Document | Purpose | Command | Location |
+|-------|----------|---------|---------|----------|
+| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | Architecture repo |
+| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repos |
+| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
 
-| Layer | Purpose | Location |
-|-------|---------|----------|
-| **vision.md** | North star philosophy (why, principles, non-goals) | File in repo root |
-| **Milestones** | Goals with progress tracking | Gitea milestones |
+Product vision inherits from and extends the organization manifesto.
 
-- **vision.md** is stable - updated rarely when direction changes
-- **Milestones** are actionable - created/closed as goals evolve
-- **Issues** are assigned to milestones to track progress
+---
 
-## Vision Document Structure
+## Manifesto (Organization Level)
 
-The vision.md file should contain the stable "why" and "who" - not progress tracking:
+The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.
+
+### Manifesto Structure
+
+```markdown
+# Manifesto
+
+## Who We Are
+Organization identity - what makes us unique.
+
+## Who We Serve
+Shared personas across all products.
+- **Persona Name**: Description, context, constraints
+
+## What They're Trying to Achieve
+Jobs to be done at the organization level.
+- "Help me [outcome] without [pain]"
+
+## What We Believe
+Core beliefs that guide how we work.
+### [Belief Category]
+- Belief point
+- Belief point
+
+## Guiding Principles
+Decision-making rules that apply everywhere.
+1. **Principle**: Explanation
+
+## Non-Goals
+What the organization explicitly does NOT do.
+- **Non-goal**: Why
+```
+
+### When to Update Manifesto
+
+- **Rarely** - this is foundational identity
+- When core beliefs change
+- When adding/removing personas served
+- When adding non-goals based on learnings
+
+### Creating a Manifesto
+
+1. Define organization identity (Who We Are)
+2. Identify shared personas (2-4 max)
+3. Articulate organization-level jobs to be done
+4. Document core beliefs (especially about AI/development)
+5. Establish guiding principles
+6. Define non-goals
+
+---
+
+## Vision (Product Level)
+
+The vision defines what a specific product does. It lives in each product repo and extends the manifesto.
+
+### Vision Structure
 
 ```markdown
 # Vision
 
-## Who We Serve (Personas)
-The people we're building for and what characterizes them.
+## Who This Product Serves
+Product-specific personas (may extend org personas).
+- **Persona Name**: Product-specific context
 
-- **Persona Name**: Brief description of who they are, their context, constraints
-
-## What They're Trying to Achieve (Jobs to Be Done)
-The outcomes our personas are trying to accomplish - in their words.
-
-- "Help me [achieve outcome] without [pain point]"
-- "Help me [do thing] so I can [benefit]"
+## What They're Trying to Achieve
+Product-specific jobs to be done.
+- "Help me [outcome] without [pain]"
 
 ## The Problem
-Current pain points that prevent our personas from achieving their jobs.
+Pain points this product addresses.
 
 ## The Solution
-How this product addresses the jobs to be done.
+How this product solves those problems.
 
-## Guiding Principles
-Core beliefs that guide decisions.
+## Product Principles
+Product-specific principles (beyond org principles).
 
 ## Non-Goals
-What we're explicitly NOT doing (and why).
+What this product explicitly does NOT do.
 ```
 
-Do NOT include goals, progress, or focus in vision.md - that's what milestones are for.
+### When to Update Vision
 
-## Defining Personas
+- When product direction shifts
+- When adding/changing personas served by this product
+- When discovering new non-goals
+- After major learnings from retros
 
-Good personas are:
-- **Specific**: Not "developers" but "solo developers shipping MVPs"
-- **Characterized**: Include constraints, context, priorities
-- **Limited**: 2-4 personas max, or you're building for everyone (no one)
+### Creating a Product Vision
 
-| Bad | Good |
-|-----|------|
-| "Users" | "Solo developer shipping side projects on evenings/weekends" |
-| "Developers" | "Small team lead coordinating 2-5 engineers" |
-| "Companies" | "Early-stage startup with no dedicated DevOps" |
+1. Reference the organization manifesto
+2. Define product-specific personas (can extend org personas)
+3. Identify product-specific jobs to be done
+4. Articulate the problem this product solves
+5. Define the solution approach
+6. Set product-specific principles (if any)
+7. Document product non-goals
+8. Create initial milestones
 
-## Defining Jobs to Be Done
+---
 
-Jobs should be:
-- **Outcome-focused**: What they want to achieve, not what they do
-- **In their voice**: How they'd describe it, not technical jargon
-- **Pain-aware**: Include what's hard about it today
+## Relationship: Manifesto → Vision
 
-Format: "Help me [outcome] without [pain]" or "Help me [action] so I can [benefit]"
+```
+Manifesto (org)          Vision (product)
+├── Shared Personas  →   Product Personas (more specific)
+├── Org Jobs         →   Product Jobs (subset/extension)
+├── Beliefs          →   (inherited, not duplicated)
+├── Principles       →   Product Principles (additional)
+└── Non-Goals        →   Product Non-Goals (additional)
+```
 
-| Bad | Good |
-|-----|------|
-| "Git integration" | "Help me commit and push without remembering git commands" |
-| "Issue tracking" | "Help me know what to work on next without checking 5 tools" |
-| "Code review" | "Help me catch bugs before they ship without slowing down" |
+### Inheritance Model
 
-## Creating a Vision
+- **Personas**: Product personas can be more specific versions of org personas
+- **Jobs**: Product jobs should trace back to org-level jobs
+- **Beliefs**: Inherited from manifesto, not duplicated in vision
+- **Principles**: Product can add specific principles; org principles apply automatically
+- **Non-Goals**: Product adds its own; org non-goals apply automatically
 
-When no vision exists:
+### Example
 
-1. **Define personas**: Who are we building for? (2-4 specific personas)
-2. **Identify jobs to be done**: What are they trying to achieve?
-3. **Articulate the problem**: What pain points prevent them from achieving their jobs?
-4. **Define the solution**: How does the product address these jobs?
-5. **Set guiding principles**: What beliefs guide decisions?
-6. **Document non-goals**: What are you explicitly NOT doing?
-7. **Create initial milestones**: 3-5 measurable goals tied to personas/jobs
+**Manifesto** (organization):
+```markdown
+## Who We Serve
+- **Solo Developer**: Individual shipping side projects, time-constrained
+```
 
-### Good Goals (Milestones)
+**Vision** (product - e.g., CLI tool):
+```markdown
+## Who This Product Serves
+- **Solo Developer (CLI user)**: Uses terminal daily, prefers keyboard over GUI
+```
+
+The product persona extends the org persona with product-specific context.
+
+---
+
+## Milestones (Goals)
+
+Milestones are product-level goals that track progress toward the vision.
+
+### Good Milestones
 
 - Specific and measurable
 - Tied to a persona and job to be done
 - Outcome-focused (not activity-focused)
-- Have clear success criteria in the description
+- Include success criteria in description
 
-| Bad | Good |
-|-----|------|
-| "Improve performance" | "Page load under 2 seconds" |
-| "Better UX" | "User can complete checkout in under 60 seconds" |
-| "More features" | "Support 3 export formats (CSV, JSON, PDF)" |
-
-### Tying Milestones to Personas
-
-Each milestone should clearly serve a persona's job to be done:
-
-```
-Milestone: "Automate routine git workflows"
-For: Solo developer
-Job: "Help me commit and push without remembering git commands"
-Success: /commit, /pr commands handle 80% of git workflows
-```
-
-Include persona context in milestone descriptions:
 ```bash
 tea milestones create --title "Automate routine git workflows" \
   --description "For: Solo developer
@@ -125,35 +177,14 @@ Job: Ship without context switching to git commands
 Success: /commit and /pr commands handle 80% of workflows"
 ```
 
-## Managing Goals with Milestones
+### Milestone-to-Vision Alignment
 
-```bash
-# List milestones with progress
-tea milestones
-tea milestones -f title,items_open,items_closed,state
+Every milestone should trace to:
+- A persona (from vision or manifesto)
+- A job to be done (from vision)
+- A measurable outcome
 
-# Create a new goal
-tea milestones create --title "Automate repetitive workflows" \
-  --description "Success: 80% of routine tasks handled by slash commands"
-
-# View issues in a milestone
-tea milestones issues "Automate repetitive workflows"
-
-# Close a completed goal
-tea milestones close "Automate repetitive workflows"
-```
-
-### Assigning Issues to Milestones
-
-When creating issues, assign them to the relevant milestone:
-
-```bash
-tea issues create --title "Add /commit command" \
-  --description "..." \
-  --milestone "Automate repetitive workflows"
-```
-
-Progress is automatically tracked through open/closed issue counts.
+---
 
 ## Aligning Issues with Vision
 
@@ -161,50 +192,49 @@ When creating or reviewing issues:
 
 1. **Check persona alignment**: Which persona does this serve?
 2. **Check job alignment**: Which job to be done does this enable?
-3. **Check goal alignment**: Does this issue support a milestone?
+3. **Check milestone alignment**: Does this issue support a goal?
 4. **Assign to milestone**: Link the issue to the relevant goal
-5. **Prioritize by focus**: Issues in priority milestones get worked first
-6. **Flag misalignment**: Issues without clear persona/milestone need justification
 
 Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
 
 ### Identifying Gaps
 
-Compare vision to current work:
-
 - **Underserved personas**: Which personas have few milestones/issues?
 - **Unaddressed jobs**: Which jobs to be done have no work toward them?
 - **Empty milestones**: Which milestones have no issues?
-- **Stalled milestones**: Which milestones have no recent progress?
-- **Orphan issues**: Are there issues without a milestone?
+- **Orphan issues**: Issues without a milestone need justification
 
-## Connecting Retros to Vision
-
-After a retrospective:
-
-1. **Review learnings**: Any that affect the vision or goals?
-2. **Milestone changes**: Should any goals be added, closed, or modified?
-3. **Non-goal additions**: Did we learn something to add to vision.md?
-4. **Progress check**: Did completed work close any milestones?
-
-### Retro-to-Vision Questions
-
-- "Did this work reveal a new goal we should add as a milestone?"
-- "Did we learn something that should become a non-goal in vision.md?"
-- "Should we close or modify any milestones based on what we learned?"
-- "Are any milestones ready to close?"
+---
 
 ## Continuous Improvement Loop
 
 ```
-Vision → Milestones → Issues → Work → Retro → (Vision/Milestones updated)
+Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
+                                                    ↓
+                                          Architecture repo issues
+                                                    ↓
+                                          Encoded into learnings +
+                                          skills/commands/agents
 ```
 
-1. **Vision** defines why and principles (stable)
-2. **Milestones** define measurable goals
-3. **Issues** are work items toward those goals
-4. **Work** implements the issues
-5. **Retros** capture learnings
-6. **Updates** refine vision and create/close milestones
+1. **Manifesto** defines organizational identity (very stable)
+2. **Vision** defines product direction (stable)
+3. **Milestones** define measurable goals (evolve)
+4. **Issues** are work items toward goals
+5. **Work** implements the issues
+6. **Retros** create issues on architecture repo
+7. **Encoding** turns insights into learnings and system improvements
 
-The vision is stable. The milestones evolve as you learn and achieve goals.
+---
+
+## Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| Where do shared personas live? | `manifesto.md` in architecture repo |
+| Where do product personas live? | `vision.md` in product repo |
+| Where do beliefs live? | `manifesto.md` only (inherited) |
+| Where do goals live? | Gitea milestones (per repo) |
+| What command for org vision? | `/manifesto` |
+| What command for product vision? | `/vision` |
+| What repo for learnings? | Architecture repo |