Simplify /retro flow: issue first, encoding later

Changed the retro flow to:
1. Retro (any repo) → Issue (architecture repo)
2. Later: Encode issue into learning file + skill/command/agent

Key changes:
- Retro now only creates issues, not learning files
- Learning files are created when the issue is worked on
- All issues go to architecture repo regardless of source repo
- Added "When the Issue is Worked On" section for encoding guidance
- Clearer separation between capturing insights and encoding them

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

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

commands/manifesto.md

@@ -0,0 +1,71 @@
+---
+description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
+---
+
+# Organization Manifesto
+
+@~/.claude/skills/vision-management/SKILL.md
+
+The manifesto defines the organization-level vision: who we are, who we serve, what we believe, and how we work. It is distinct from product-level vision (see `/vision`).
+
+## Process
+
+1. **Check for manifesto**: Look for `manifesto.md` in the current repo root.
+
+2. **If no manifesto exists**:
+   - Ask if the user wants to create one
+   - Guide through defining:
+     1. **Who We Are**: Organization identity
+     2. **Who We Serve**: 2-4 specific personas with context and constraints
+     3. **What They're Trying to Achieve**: Jobs to be done in their voice
+     4. **What We Believe**: Core beliefs including stance on AI-augmented development
+     5. **Guiding Principles**: Decision-making rules
+     6. **Non-Goals**: What we explicitly don't do
+   - Create `manifesto.md`
+
+3. **If manifesto exists**:
+   - Display formatted summary of the manifesto
+
+## Output Format
+
+When displaying an existing manifesto:
+
+```
+## Who We Are
+
+[Identity summary from manifesto]
+
+## Who We Serve
+
+- **[Persona 1]**: [Brief description]
+- **[Persona 2]**: [Brief description]
+- **[Persona 3]**: [Brief description]
+
+## What They're Trying to Achieve
+
+- "[Job to be done 1]"
+- "[Job to be done 2]"
+- "[Job to be done 3]"
+
+## What We Believe
+
+[Summary of key beliefs - especially AI-augmented development stance]
+
+## Guiding Principles
+
+1. [Principle 1]
+2. [Principle 2]
+3. [Principle 3]
+
+## Non-Goals
+
+- [Non-goal 1]
+- [Non-goal 2]
+```
+
+## Guidelines
+
+- The manifesto is the **organization-level** document - it applies across all products
+- Update rarely - this is foundational identity, not tactical direction
+- Product repos reference the manifesto but have their own `vision.md`
+- Use `/vision` for product-level vision management

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?
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/ai`:
 
-   If any vision updates are needed:
-   - Present suggested changes to `vision.md`
-   - Ask for approval
-   - Update the vision file and sync to Gitea
+   ```bash
+   tea issues create -r flowmade-one/ai \
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]
 
-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:
+   ## Insight
+   [The specific learning - be concrete and actionable]
 
-```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>" --milestone "<milestone>"
-```
+   ## 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]
 
-## Milestone Assignment
+   ## Governance
+   [What this means for how we work going forward]"
+   ```
 
-Before creating issues, fetch available milestones:
+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)
 
-```bash
-tea milestones -f title,description
-```
+   If vision updates are needed, present suggested changes and ask for approval.
 
-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 the Issue is Worked On
 
-## Issue Format
+When encoding a learning issue, the implementer should:
 
-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).
+   ```markdown
+   # [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

learnings/README.md

@@ -0,0 +1,88 @@
+# Learnings
+
+This folder captures learnings from retrospectives and day-to-day work. Learnings serve three purposes:
+
+1. **Historical record**: What we learned and when
+2. **Governance reference**: Why we work the way we do
+3. **Encoding source**: Input that gets encoded into skills, commands, and agents
+
+## The Learning Flow
+
+```
+Experience → Learning captured → Encoded into system → Knowledge is actionable
+                   ↓
+            Stays here for:
+            - Historical reference
+            - Governance validation
+            - Periodic review
+```
+
+Learnings are **not** the final destination. They are inputs that get encoded into commands, skills, and agents where Claude can actually use them. But we keep the learning file as a record of *why* we encoded what we did.
+
+## Writing a Learning
+
+Create a new file: `YYYY-MM-DD-short-title.md`
+
+Use this template:
+
+```markdown
+# [Title]
+
+**Date**: YYYY-MM-DD
+**Context**: What triggered this learning (task, incident, observation)
+
+## Learning
+
+The insight we gained. Be specific and actionable.
+
+## Encoded In
+
+Where this learning has been (or will be) encoded:
+
+- `skills/xxx/SKILL.md` - What was added/changed
+- `commands/xxx.md` - What was added/changed
+- `agents/xxx/agent.md` - What was added/changed
+
+If not yet encoded, note: "Pending: Issue #XX"
+
+## Governance
+
+What this learning means for how we work going forward. This is the "why" that justifies the encoding.
+```
+
+## Encoding Process
+
+1. **Capture the learning** in this folder
+2. **Create an issue** to encode it into the appropriate location
+3. **Update the skill/command/agent** with the encoded knowledge
+4. **Update the learning file** with the "Encoded In" references
+
+The goal: Claude should be able to *use* the learning, not just *read* about it.
+
+## What Gets Encoded Where
+
+| Learning Type | Encode In |
+|---------------|-----------|
+| How to use a tool | `skills/` |
+| Workflow improvement | `commands/` |
+| Subtask behavior | `agents/` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
+## Periodic Review
+
+Periodically review learnings to:
+
+- Verify encoded locations still reflect the learning
+- Check if governance is still being followed
+- Identify patterns across multiple learnings
+- Archive or update outdated learnings
+
+## Naming Convention
+
+Files follow the pattern: `YYYY-MM-DD-short-kebab-title.md`
+
+Examples:
+- `2024-01-15-always-use-comments-flag.md`
+- `2024-01-20-verify-before-cleanup.md`
+- `2024-02-01-small-prs-merge-faster.md`