Add vertical vs horizontal slicing guidance

Adds guidance to prefer vertical slices (user-visible value) over horizontal slices (technical layers) when planning and writing issues. roadmap-planning skill: - New "Vertical vs Horizontal Slices" section - Demo test: "Can a user demo/test this independently?" - Good vs bad examples table - When horizontal slices are acceptable issue-writing skill: - New "Vertical Slices" section - Demo test guidance - Good vs bad issue titles table - User-focused issue framing examples Closes #31 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Mark skills as not user-invocable
2026-01-09 13:21:52 +01:00 · 2026-01-09 13:01:19 +01:00 · 2026-01-08 14:19:56 +01:00 · 2026-01-08 10:26:10 +01:00 · 2026-01-08 10:24:10 +01:00 · 2026-01-07 23:58:16 +01:00
31 changed files with 2377 additions and 186 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,23 +1,37 @@
-# 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
+git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
-cd ai
+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/         # Auto-triggered capabilities
+├── skills/         # Knowledge modules (auto-triggered)
-├── agents/         # Subagents with isolated context
+├── agents/         # Focused subtask handlers (isolated context)
 ├── scripts/        # Hook scripts (pre-commit, token loading)
 ├── settings.json   # Claude Code settings
 └── Makefile        # Install/uninstall symlinks
@@ -25,6 +39,29 @@ ai/
 All files symlink to `~/.claude/` via `make install`.
 ## Two Levels of Vision
 | Level | Document | Command | Purpose |
 |-------|----------|---------|---------|
 | Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
 | Product | `vision.md` | `/vision` | Product-specific direction and goals |
 See the manifesto for our identity, personas, and beliefs about AI-augmented development.
 ## Available Commands
 | 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
 Uses `tea` CLI for issue/PR management:
@@ -37,16 +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 |
+### Skills
-|---------|-------------|
+Knowledge modules that teach Claude how to do something.
 | `/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 from completed work, create improvement issues |
-## Usage
+- **Purpose**: Encode best practices and tool knowledge
 - **Location**: `skills/<name>/SKILL.md`
 - **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
-This project is meant to be used alongside Claude Code to enhance productivity and maintain consistent workflows.
+### 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
--- a/README.md
+++ b/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
+git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
-cd ai
+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
--- a/VISION.md
+++ b/VISION.md
@@ -1,5 +1,32 @@
 # Vision
 This product vision builds on the [organization manifesto](manifesto.md).
 ## Who This Product Serves
 ### Flowmade Developers
 The team building Flowmade's platform. They need efficient, consistent AI workflows to deliver on the organization's promise: helping domain experts create software without coding.
 *Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
 ### AI-Augmented Developers
 Developers in the broader community who want to treat AI assistance as a structured tool. They benefit from our "build in public" approach - adopting and adapting our workflows for their own teams.
 *Extends: The manifesto's commitment to sharing practices with the developer community.*
 ## What They're Trying to Achieve
 These trace back to organization-level jobs:
 | Product Job | Enables Org Job |
 |-------------|-----------------|
 | "Help me work consistently with AI across sessions" | "Help me deliver maintainable solutions to clients faster" |
 | "Help me encode best practices so AI applies them" | "Help me reduce dependency on developers for business process changes" |
 | "Help me manage issues and PRs without context switching" | "Help me deliver maintainable solutions to clients faster" |
 | "Help me capture and share learnings from my work" | (Build in public commitment) |
 ## The Problem
 AI-assisted development is powerful but inconsistent. Claude Code can help with nearly any task, but without structure:
@@ -9,94 +36,60 @@ AI-assisted development is powerful but inconsistent. Claude Code can help with
 - Context gets lost when switching between tasks
 - There's no shared vocabulary for common patterns
-The gap isn't in AI capability—it's in how we use it.
+The gap isn't in AI capability - it's in how we use it.
 ## The Solution
-This project provides a **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
+A **composable toolkit** for Claude Code that turns ad-hoc AI assistance into structured, repeatable workflows.
 Instead of asking Claude to "help with issues" differently each time, you run `/work-issue 42` and get a consistent workflow: fetch the issue, create a branch, plan the work, implement, commit with proper references, and create a PR.
-The key insight: **encode your team's best practices into reusable components** that Claude can apply consistently.
+### Architecture
-## Composable Components
+Three component types that stack together:
-The system is built from three types of components that stack together:
+| Component | Purpose | Example |
 |-----------|---------|---------|
 | **Skills** | Knowledge modules - teach Claude how to do something | `gitea`, `issue-writing` |
 | **Agents** | Focused subtask handlers in isolated context | `code-reviewer` |
 | **Commands** | User workflows - orchestrate skills and agents | `/work-issue`, `/dashboard` |
-### Skills
+Skills don't act on their own. Agents handle complex subtasks in isolation. Commands are the entry points that tie it together.
-Skills are knowledge modules—focused documents that teach Claude how to do something well.
+## Product Principles
-Examples:
+These extend the organization's guiding principles:
 - `issue-writing`: How to structure clear, actionable issues
 - `gitea`: How to use the Gitea CLI for issue/PR management
 - `backlog-grooming`: What makes a healthy backlog
 Skills don't do anything on their own. They're building blocks.
 ### Agents
 Agents combine multiple skills into specialized personas that can work autonomously.
 The `product-manager` agent combines issue-writing, backlog-grooming, and roadmap-planning skills to handle complex PM tasks. It can explore the codebase, plan features, and create well-structured issues—all with isolated context so it doesn't pollute the main conversation.
 Agents enable:
 - **Parallel processing**: Multiple agents can work simultaneously
 - **Context preservation**: Each agent maintains its own focused context
 - **Complex workflows**: Combine skills for multi-step tasks
 ### Commands
 Commands are the user-facing entry points—what you actually invoke.
 When you run `/plan-issues add dark mode`, the command:
 1. Understands what you're asking for
 2. Invokes the right agents and skills
 3. Guides you through the workflow with approvals
 4. Takes action (creates issues, PRs, etc.)
 Commands make the power of skills and agents accessible through simple invocations.
 ## Target Users
 This toolkit is for:
 - **Developers using Claude Code** who want consistent, efficient workflows
 - **Teams** who want to encode and share their best practices
 - **Gitea/Git users** who want seamless issue and PR management integrated into their AI workflow
 You should have:
 - Claude Code CLI installed
 - A Gitea instance (or adapt the tooling for GitHub/GitLab)
 - Interest in treating AI assistance as a structured tool, not just a chat interface
 ## Guiding Principles
 ### Encode, Don't Repeat
 If you find yourself explaining the same thing to Claude repeatedly, that's a skill waiting to be written. Capture it once, use it everywhere.
 ### Composability Over Complexity
-Small, focused components that combine well beat large, monolithic solutions. A skill should do one thing. An agent should serve one role. A command should trigger one workflow.
+Small, focused components that combine well beat large, monolithic solutions. A skill does one thing. An agent serves one role. A command triggers one workflow.
 *Extends: "Small teams, big leverage"*
 ### Approval Before Action
-Destructive or significant actions should require user approval. Commands should show what they're about to do and ask before doing it. This builds trust and catches mistakes.
+Destructive or significant actions require user approval. Commands show what they're about to do and ask before doing it.
-### Use the Tools to Build the Tools
+*Extends: Non-goal "Replacing human judgment"*
-This project uses its own commands to manage itself. Issues are created with `/create-issue`. Features are planned with `/plan-issues`. PRs are reviewed with `/review-pr`. Dogfooding ensures the tools actually work.
+### Dogfooding
 This project uses its own commands to manage itself. Issues are created with `/create-issue`. PRs are reviewed with `/review-pr`. If the tools don't work for us, they won't work for anyone.
 *Extends: "Ship to learn"*
 ### Progressive Disclosure
-Simple things should be simple. `/dashboard` just shows your issues and PRs. But the system supports complex workflows when you need them. Don't require users to understand the full architecture to get value.
+Simple things should be simple. `/dashboard` just shows your issues and PRs. Complex workflows are available when needed, but not required to get value.
-## What This Is Not
+*Extends: "Opinionated defaults, escape hatches available"*
-This is not:
+## Non-Goals
 - A replacement for Claude Code—it enhances it
 - A rigid framework—adapt it to your needs
 - Complete—it grows as we discover new patterns
-It's a starting point for treating AI-assisted development as a first-class engineering concern.
+These extend the organization's non-goals:
 - **Replacing Claude Code.** This enhances Claude Code, not replaces it. The toolkit adds structure; Claude provides the capability.
 - **One-size-fits-all workflows.** Teams should adapt these patterns to their needs. We provide building blocks, not a rigid framework.
 - **Feature completeness.** The toolkit grows as we discover new patterns. It's a starting point, not an end state.
--- a/agents/code-reviewer/AGENT.md
+++ b/agents/code-reviewer/AGENT.md
@@ -5,6 +5,9 @@ description: Automated code review of pull requests. Reviews PRs for quality, bu
 # The structured output format doesn't require opus-level reasoning.
 model: sonnet
 skills: gitea, code-review
 disallowedTools:
  - Edit
  - Write
 ---
 You are a code review specialist that provides immediate, structured feedback on pull request changes.
@@ -22,7 +25,7 @@ You will receive a PR number to review. Follow this process:
   - **Test Coverage**: Missing tests, untested edge cases
 3. Generate a structured review comment
 4. Post the review using `tea comment <number> "<review body>"`
-5. **If verdict is LGTM**: Approve with `tea pulls approve <number>`, then auto-merge with `tea pulls merge <number> --style rebase`
+5. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`
 6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
 ## Review Comment Format
--- a/agents/product-manager/AGENT.md
+++ b/agents/product-manager/AGENT.md
@@ -1,25 +0,0 @@
 ---
 name: product-manager
 description: Backlog management and roadmap planning specialist. Use for batch issue operations, comprehensive backlog reviews, or feature planning that requires codebase exploration.
 # Model: sonnet handles planning and issue-writing well.
 # Tasks follow structured patterns from skills; opus not required.
 model: sonnet
 skills: gitea, issue-writing, backlog-grooming, roadmap-planning
 ---
 You are a product manager specializing in backlog management and roadmap planning.
 ## Capabilities
 You can:
 - Review and improve existing issues
 - Create new well-structured issues
 - Analyze the backlog for gaps and priorities
 - Plan feature breakdowns
 - Maintain roadmap clarity
 ## Behavior
 - Always fetch current issue state before making changes
 - Ask for approval before creating or modifying issues
 - Provide clear summaries of actions taken
--- a/commands/create-issue.md
+++ b/commands/create-issue.md
@@ -7,13 +7,37 @@ argument-hint: [title] or "batch"
@~/.claude/skills/gitea/SKILL.md
 ## Milestone Assignment
 Before creating issues, fetch available milestones:
 ```bash
 tea milestones -f title,description
 ```
 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
 Include `--milestone "<milestone>"` in the create command when a milestone is assigned.
 ## Single Issue (default)
-If title provided, create an issue with that title and ask for description.
+
 If title provided:
 1. Create an issue with that title
 2. Ask for description
 3. Assign to appropriate milestone (see above)
 4. Ask if this issue depends on any existing issues
 5. If dependencies exist, link them: `tea issues deps add <new-issue> <blocker>`
 ## Batch Mode
 If $1 is "batch":
 1. Ask user for the plan/direction
-2. Generate list of issues with titles and descriptions
+2. Fetch available milestones
-3. Show for approval
+3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
-4. Create each issue
+4. Show for approval
-5. Display all created issue numbers
+5. Create each issue with milestone (in dependency order)
 6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
 7. Display all created issue numbers with dependency graph
--- a/commands/create-repo.md
+++ b/commands/create-repo.md
@@ -0,0 +1,208 @@
 ---
 description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
 argument-hint: <repo-name>
 context: fork
 ---
 # Create Repository
@~/.claude/skills/repo-conventions/SKILL.md
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/claude-md-writing/SKILL.md
@~/.claude/skills/gitea/SKILL.md
 Create a new repository with Flowmade's standard structure.
 ## Process
 1. **Get repository name**: Use `$1` or ask the user
   - Validate: lowercase, hyphens only, no `flowmade-` prefix
   - Check it doesn't already exist: `tea repos flowmade-one/<name>`
 2. **Determine visibility**:
   - Ask: "Should this repo be public (open source) or private (proprietary)?"
   - Refer to repo-conventions skill for guidance on open vs proprietary
 3. **Gather vision context**:
   - Read the organization manifesto: `../architecture/manifesto.md`
   - Ask: "What does this product do? (one sentence)"
   - Ask: "Which manifesto personas does it serve?"
   - Ask: "What problem does it solve?"
 4. **Create the repository on Gitea**:
   ```bash
   tea repos create --name <repo-name> --private/--public --description "<description>"
   ```
 5. **Clone and set up structure**:
   ```bash
   # Clone the new repo
   git clone ssh://git@git.flowmade.one/flowmade-one/<repo-name>.git
   cd <repo-name>
   ```
 6. **Create vision.md**:
   - Use the vision structure template from vision-management skill
   - Link to `../architecture/manifesto.md`
   - Fill in based on user's answers
 7. **Create CLAUDE.md** (following claude-md-writing skill):
   ```markdown
   # <Repo Name>
   <One-line description from step 3>
   ## Organization Context
   This repo is part of Flowmade. See:
   - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
   - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
   - [Vision](./vision.md) - what this specific product does
   ## Setup
   ```bash
   # TODO: Add setup instructions
   ```
   ## Project Structure
   TODO: Document key directories once code exists.
   ## Development
   ```bash
   make build    # Build the project
   make test     # Run tests
   make lint     # Run linters
   ```
   ## Architecture
   TODO: Document key patterns and conventions once established.
   ```
 8. **Create Makefile** (basic template):
   ```makefile
   .PHONY: build test lint
   build:
   	@echo "TODO: Add build command"
   test:
   	@echo "TODO: Add test command"
   lint:
   	@echo "TODO: Add lint command"
   ```
 9. **Create CI workflow**:
   ```bash
   mkdir -p .gitea/workflows
   ```
   Create `.gitea/workflows/ci.yaml`:
   ```yaml
   name: CI
   on:
     push:
       branches: [main]
     pull_request:
       branches: [main]
   jobs:
     build:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - name: Build
           run: make build
         - name: Test
           run: make test
         - name: Lint
           run: make lint
   ```
 10. **Create .gitignore** (basic, expand based on language):
    ```
    # IDE
    .idea/
    .vscode/
    *.swp
    # OS
    .DS_Store
    Thumbs.db
    # Build artifacts
    /dist/
    /build/
    /bin/
    # Dependencies (language-specific, add as needed)
    /node_modules/
    /vendor/
    ```
 11. **Initial commit and push**:
    ```bash
    git add .
    git commit -m "Initial repository structure
    - vision.md linking to organization manifesto
    - CLAUDE.md with project instructions
    - CI workflow template
    - Basic Makefile
    🤖 Generated with [Claude Code](https://claude.com/claude-code)
    Co-Authored-By: Claude <noreply@anthropic.com>"
    git push -u origin main
    ```
 12. **Report success**:
    ```
    Repository created: https://git.flowmade.one/flowmade-one/<repo-name>
    Next steps:
    1. cd ../<repo-name>
    2. Update CLAUDE.md with actual setup instructions
    3. Update Makefile with real build commands
    4. Start building!
    ```
 ## Output Example
 ```
 ## Creating Repository: my-service
 Visibility: Private (proprietary)
 Description: Internal service for processing events
 ### Files Created
 - vision.md (linked to manifesto)
 - CLAUDE.md (project instructions)
 - Makefile (build template)
 - .gitea/workflows/ci.yaml (CI pipeline)
 - .gitignore (standard ignores)
 ### Repository URL
 https://git.flowmade.one/flowmade-one/my-service
 ### Next Steps
 1. cd ../my-service
 2. Update CLAUDE.md with setup instructions
 3. Update Makefile with build commands
 4. Start coding!
 ```
 ## Guidelines
 - Always link vision.md to the sibling architecture repo
 - Keep initial structure minimal - add complexity as needed
 - CI should pass on empty repo (use placeholder commands)
 - Default to private unless explicitly open-sourcing
--- a/commands/groom.md
+++ b/commands/groom.md
@@ -11,23 +11,27 @@ argument-hint: [issue-number]
 ## If issue number provided ($1):
-1. **Fetch the issue** details
+1. **Fetch the issue** details with `tea issues <number> --comments`
-2. **Evaluate** against grooming checklist
+2. **Check dependencies** with `tea issues deps list <number>`
-3. **Suggest improvements** for:
+3. **Evaluate** against grooming checklist
 4. **Suggest improvements** for:
   - Title clarity
   - Description completeness
   - Acceptance criteria quality
   - Scope definition
-4. **Ask user** if they want to apply changes
+   - Missing or incorrect dependencies
-5. **Update issue** if approved
+5. **Ask user** if they want to apply changes
 6. **Update issue** if approved
 7. **Link/unlink dependencies** if needed: `tea issues deps add/remove <issue> <dep>`
 ## If no argument (groom all):
 1. **List open issues**
-2. **Review each** against grooming checklist
+2. **Review each** against grooming checklist (including dependencies)
 3. **Categorize**:
-   - Ready: Well-defined, can start work
+   - Ready: Well-defined, dependencies linked, can start work
-   - Needs work: Missing info or unclear
+   - Blocked: Has unresolved dependencies
   - Needs work: Missing info, unclear, or missing dependency links
   - Stale: No longer relevant
-4. **Present summary** table
+4. **Present summary** table with dependency status
-5. **Offer to improve** issues that need work
+5. **Offer to improve** issues that need work (including linking dependencies)
--- a/commands/improve.md
+++ b/commands/improve.md
@@ -0,0 +1,84 @@
 ---
 description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
 argument-hint:
 context: fork
 ---
 # Improvement Analysis
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
@~/.claude/skills/roadmap-planning/SKILL.md
 ## Process
 1. **Read the vision**: Load `vision.md` from the repo root.
   - If no vision exists, suggest running `/vision` first
 2. **Fetch current backlog**: Get all open issues from Gitea using `tea issues`
 3. **Analyze alignment**:
   For each vision goal, check:
   - Are there issues supporting this goal?
   - Is there recent activity/progress?
   - Are issues blocked or stalled?
   For each open issue, check:
   - Does it align with a vision goal?
   - Is it supporting the current focus?
 4. **Identify gaps and opportunities**:
   - **Unsupported goals**: Vision goals with no issues
   - **Stalled goals**: Goals with issues but no recent progress
   - **Orphan issues**: Issues that don't support any goal
   - **Focus misalignment**: Issues not aligned with current focus getting priority
   - **Missing non-goals**: Patterns suggesting things we should explicitly avoid
 5. **Present findings**:
   ```
   ## Vision Alignment Report
   ### Goals Coverage
   - Goal 1: [status] - N issues, [progress]
   - Goal 2: [status] - N issues, [progress]
   ### Gaps Identified
   1. [Gap description]
      Suggestion: [concrete action]
   2. [Gap description]
      Suggestion: [concrete action]
   ### Orphan Issues
   - #N: [title] - No goal alignment
   ### Recommended Actions
   1. [Action with rationale]
   2. [Action with rationale]
   ```
 6. **Offer to take action**:
   For unsupported goals:
   - Ask if user wants to plan issues for the gap
   - If yes, run the `/plan-issues` workflow for that goal
   - This breaks down the goal into concrete, actionable issues
   For other findings:
   - Re-prioritize issues based on focus
   - Close or re-scope orphan issues
   - Update vision with suggested changes
   Always ask for approval before making changes.
 ## Guidelines
 - Focus on actionable improvements, not just observations
 - Prioritize suggestions by impact on vision goals
 - Keep suggestions specific and concrete
 - One issue per improvement (don't bundle)
 - Reference specific goals when suggesting new issues
--- a/commands/manifesto.md
+++ b/commands/manifesto.md
@@ -0,0 +1,72 @@
 ---
 description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
 argument-hint:
 ---
 # 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
--- a/commands/plan-issues.md
+++ b/commands/plan-issues.md
@@ -1,6 +1,7 @@
 ---
-description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues.
+description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
 argument-hint: <feature-description>
 context: fork
 ---
 # Plan Feature: $1
@@ -8,18 +9,26 @@ argument-hint: <feature-description>
@~/.claude/skills/gitea/SKILL.md
@~/.claude/skills/roadmap-planning/SKILL.md
@~/.claude/skills/issue-writing/SKILL.md
@~/.claude/skills/vision-management/SKILL.md
-1. **Understand the feature**: Analyze what "$1" involves
+1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
-2. **Explore the codebase** if needed to understand context
+2. **Identify persona**: Which persona does "$1" serve?
-3. **Break down** into discrete, actionable issues:
+3. **Identify job**: Which job to be done does this enable?
 4. **Understand the feature**: Analyze what "$1" involves
 5. **Explore the codebase** if needed to understand context
 6. **Break down** into discrete, actionable issues:
   - Each issue should be independently completable
   - Clear dependencies between issues
   - Appropriate scope (not too big, not too small)
-4. **Present the plan**:
+7. **Present the plan** (include vision alignment if vision exists):
   ```
   ## Proposed Issues for: $1
   For: [Persona name]
   Job: "[Job to be done this enables]"
   Supports: [Milestone/Goal name]
   1. [Title] - Brief description
      Dependencies: none
@@ -30,7 +39,13 @@ argument-hint: <feature-description>
      Dependencies: #1, #2
   ```
-5. **Ask for approval** before creating issues
+   If the feature doesn't align with any persona/job/goal, note this and ask if:
-6. **Create issues** in order
+   - A new persona or job should be added to the vision
-7. **Update dependencies** with actual issue numbers after creation
+   - A new milestone should be created
-8. **Present summary** with links to created issues
+   - This should be added as a non-goal
   - Proceed anyway (with justification)
 8. **Ask for approval** before creating issues
 9. **Create issues** in dependency order (blockers first)
 10. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
 11. **Present summary** with links to created issues and dependency graph
--- a/commands/retro.md
+++ b/commands/retro.md
@@ -1,11 +1,22 @@
 ---
-description: Run a retrospective on completed work. Captures learnings and creates improvement issues in the AI repo.
+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.
+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
@@ -16,49 +27,90 @@ Capture learnings from completed AI-assisted work to improve the workflow.
   - What worked well?
   - Any specific improvement ideas?
-3. **Analyze and categorize**: Group learnings into:
+3. **Identify insights**: For each insight, determine:
-   - **Prompt improvements**: Better instructions for commands/skills
+   - **What was learned**: The specific insight
-   - **Missing capabilities**: New commands or skills needed
+   - **Where to encode it**: Which skill, command, or agent should change?
-   - **Tool issues**: Problems with tea CLI, git, or other tools
+   - **Governance impact**: What does this mean for how we work?
   - **Context gaps**: Missing documentation or skills
-4. **Generate improvement issues**: For each actionable improvement, create an issue in the AI repo using:
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
-```bash
+   ```bash
-tea issues create -r flowmade-one/ai --title "<title>" --description "<body>"
+   tea issues create -r flowmade-one/architecture \
-```
+     --title "[Learning] <brief description>" \
     --description "## Context
   [Task that triggered this insight]
-## Issue Format
+   ## Insight
   [The specific learning - be concrete and actionable]
-Use this structure for retrospective issues:
+   ## 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]
-```markdown
+   ## Governance
-## Context
+   [What this means for how we work going forward]"
-What task triggered this learning (brief).
+   ```
-## Problem / Observation
+5. **Connect to vision**: Check if insight affects vision:
-What was the friction point or insight.
+   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
-## Suggested Improvement
+   If vision updates are needed, present suggested changes and ask for approval.
 Concrete, actionable change to make.
-## Affected Files
+## When the Issue is Worked On
- commands/xxx.md
+
- skills/xxx/SKILL.md
+When encoding a learning issue, the implementer should:
-```
+
 1. **Create learning file**: `learnings/YYYY-MM-DD-short-title.md`
   ```markdown
   # [Learning Title]
   **Date**: YYYY-MM-DD
   **Context**: [Task that triggered this learning]
   **Issue**: #XX
   ## Learning
   [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:
+Add appropriate labels to issues:
- `retrospective` - Always add this
+- `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
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
- One issue per improvement (don't bundle unrelated things)
+- **Be specific**: Vague insights can't be encoded
- Reference specific commands/skills when relevant
+- **One issue per insight**: Don't bundle unrelated things
- Keep issues small and focused
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
- Skip creating issues for one-off edge cases that won't recur
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur
--- a/commands/review-pr.md
+++ b/commands/review-pr.md
@@ -7,7 +7,7 @@ argument-hint: <pr-number>
@~/.claude/skills/gitea/SKILL.md
-1. **View PR details** including description and metadata
+1. **View PR details** with `--comments` flag to see description, metadata, and discussion
 2. **Get the diff** to review the changes
 Review the changes and provide feedback on:
@@ -20,3 +20,19 @@ Ask the user what action to take:
 - **Merge**: Post review summary as comment, then merge with rebase style
 - **Request changes**: Leave feedback without merging
 - **Comment only**: Add a comment for discussion
 ## Merging
 Always use tea CLI for merges to preserve user attribution:
 ```bash
 tea pulls merge <number> --style rebase
 ```
 For review comments, use `tea comment` since `tea pulls review` is interactive-only:
 ```bash
 tea comment <number> "<review summary>"
 ```
 > **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.
--- a/commands/roadmap.md
+++ b/commands/roadmap.md
@@ -1,5 +1,6 @@
 ---
 description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
 argument-hint:
 ---
 # Roadmap View
--- a/commands/update-claude-md.md
+++ b/commands/update-claude-md.md
@@ -0,0 +1,166 @@
 ---
 description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
 argument-hint:
 context: fork
 ---
 # Update CLAUDE.md
@~/.claude/skills/claude-md-writing/SKILL.md
@~/.claude/skills/repo-conventions/SKILL.md
 Update or create CLAUDE.md for the current repository with proper organization context and current project state.
 ## Process
 1. **Check for existing CLAUDE.md**: Look for `CLAUDE.md` in repo root
 2. **If CLAUDE.md exists**:
   - Read current content
   - Identify which sections exist
   - Note any custom content to preserve
 3. **Explore the project**:
   - Scan directory structure
   - Identify language/framework (go.mod, package.json, Cargo.toml, etc.)
   - Find key patterns (look for common directories, config files)
   - Check for Makefile or build scripts
 4. **Check organization context**:
   - Does it have the "Organization Context" section?
   - Does it link to `../architecture/manifesto.md`?
   - Does it link to `../architecture/repos.md`?
   - Does it link to `./vision.md`?
 5. **Gather missing information**:
   - If no one-line description: Ask user
   - If no architecture section: Infer from code or ask user
 6. **Update CLAUDE.md**:
   **Always ensure these sections exist:**
   ```markdown
   # [Project Name]
   [One-line description]
   ## Organization Context
   This repo is part of Flowmade. See:
   - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
   - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
   - [Vision](./vision.md) - what this specific product does
   ## Setup
   [From existing or ask user]
   ## Project Structure
   [Generate from actual directory scan]
   ## Development
   [From Makefile or existing]
   ## Architecture
   [From existing or infer from code patterns]
   ```
 7. **Preserve custom content**:
   - Keep any additional sections the user added
   - Don't remove information, only add/update
   - If unsure, ask before removing
 8. **Show diff and confirm**:
   - Show what will change
   - Ask user to confirm before writing
 ## Section-Specific Guidance
 ### Project Structure
 Generate from actual directory scan:
 ```bash
 # Scan top-level and key subdirectories
 ls -la
 ls pkg/ cmd/ internal/ src/ (as applicable)
 ```
 Format as tree showing purpose:
 ```markdown
 ## Project Structure
 \`\`\`
 project/
 ├── cmd/           # Entry points
 ├── pkg/           # Shared packages
 │   ├── domain/    # Business logic
 │   └── infra/     # Infrastructure
 └── internal/      # Private packages
 \`\`\`
 ```
 ### Development Commands
 Extract from Makefile if present:
 ```bash
 grep -E "^[a-zA-Z_-]+:" Makefile | head -10
 ```
 Or from package.json scripts, Cargo.toml, etc.
 ### Architecture
 Look for patterns:
 - Event sourcing: Check for aggregates, events, projections
 - Clean architecture: Check for domain, application, infrastructure layers
 - API style: REST, gRPC, GraphQL
 If unsure, ask: "What are the key architectural patterns in this project?"
 ## Output Example
 ```
 ## Updating CLAUDE.md
 ### Current State
 - Has description: ✓
 - Has org context: ✗ (will add)
 - Has setup: ✓
 - Has structure: Outdated (will update)
 - Has development: ✓
 - Has architecture: ✗ (will add)
 ### Changes
 + Adding Organization Context section
 ~ Updating Project Structure (new directories found)
 + Adding Architecture section
 ### New Project Structure
 \`\`\`
 arcadia/
 ├── cmd/
 ├── pkg/
 │   ├── aether/      # Event sourcing runtime
 │   ├── iris/        # WASM UI framework
 │   ├── adl/         # Domain language
 │   └── ...
 └── internal/
 \`\`\`
 Proceed with update? [y/n]
 ```
 ## Guidelines
 - Always add Organization Context if missing
 - Preserve existing custom sections
 - Update Project Structure from actual filesystem
 - Don't guess at Architecture - ask if unclear
 - Show changes before writing
 - Reference claude-md-writing skill for best practices
--- a/commands/vision.md
+++ b/commands/vision.md
@@ -0,0 +1,209 @@
 ---
 description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
 argument-hint: [goals]
 ---
 # Product Vision
@~/.claude/skills/vision-management/SKILL.md
@~/.claude/skills/gitea/SKILL.md
 This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
 ## Architecture
 | 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` |
 Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
 ## Manifesto Location
 The manifesto lives in the sibling `architecture` repo:
 ```
 org/
 ├── architecture/
 │   └── manifesto.md    ← organization manifesto
 ├── product-a/
 │   └── vision.md       ← extends ../architecture/manifesto.md
 └── product-b/
    └── vision.md
 ```
 Look for manifesto in this order:
 1. `./manifesto.md` (if this IS the architecture repo)
 2. `../architecture/manifesto.md` (sibling repo)
 ## Process
 1. **Load organization context**: Find and read `manifesto.md` using the location rules above
   - Extract personas (Who We Serve)
   - Extract jobs to be done (What They're Trying to Achieve)
   - Extract guiding principles
   - Extract non-goals
   - If not found, warn and continue without inheritance context
 2. **Check for product vision**: Look for `vision.md` in the current repo root
 3. **If no vision exists**:
   - Show the organization manifesto summary
   - Ask if the user wants to create a product vision
   - Guide them through defining (with inheritance):
     **Who This Product Serves**
     - Show manifesto personas first
     - Ask: "Which personas does this product serve? How does it extend or specialize them?"
     - Product personas should reference org personas with product-specific context
     **What They're Trying to Achieve**
     - Show manifesto jobs first
     - Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
     - Use a table format showing the connection
     **The Problem**
     - What pain points does this product solve?
     **The Solution**
     - How does this product address those jobs?
     **Product Principles**
     - Show manifesto principles first
     - Ask: "Any product-specific principles? These should extend, not duplicate."
     - Each principle should note what org principle it extends
     **Product Non-Goals**
     - Show manifesto non-goals first
     - Ask: "Any product-specific non-goals?"
     - Org non-goals apply automatically
   - Create `vision.md` with proper inheritance markers
   - Ask about initial goals, create as Gitea milestones
 4. **If vision exists**:
   - Display organization context summary
   - Display the product vision from `vision.md`
   - Validate inheritance (warn if vision duplicates rather than extends)
   - 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
 5. **Managing Goals (milestones)**:
   ```bash
   # List milestones with progress
   tea milestones
   # Create a new goal
   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>
   # Close a completed goal
   tea milestones close <milestone-name>
   ```
 ## Vision Structure Template
 ```markdown
 # Vision
 This product vision builds on the [organization manifesto](../architecture/manifesto.md).
 ## Who This Product Serves
 ### [Persona Name]
 [Product-specific description]
 *Extends: [Org persona] (from manifesto)*
 ## What They're Trying to Achieve
 These trace back to organization-level jobs:
 | Product Job | Enables Org Job |
 |-------------|-----------------|
 | "[Product-specific job]" | "[Org job from manifesto]" |
 ## The Problem
 [Pain points this product addresses]
 ## The Solution
 [How this product solves those problems]
 ## Product Principles
 These extend the organization's guiding principles:
 ### [Principle Name]
 [Description]
 *Extends: "[Org principle]"*
 ## Non-Goals
 These extend the organization's non-goals:
 - **[Non-goal].** [Explanation]
 ```
 ## Output Format
 ```
 ## Organization Context
 From manifesto.md:
 - **Personas**: [list from manifesto]
 - **Core beliefs**: [key beliefs]
 - **Principles**: [list]
 ## Product: [Name]
 ### Who This Product Serves
 - **[Persona 1]**: [Product-specific description]
  ↳ Extends: [Org persona]
 ### What They're Trying to Achieve
 | Product Job | → Org Job |
 |-------------|-----------|
 | [job] | [org job it enables] |
 ### Vision Summary
 [Problem/solution from vision.md]
 ### Goals (Milestones)
 | Goal | For | Progress | Due |
 |------|-----|----------|-----|
 | [title] | [Persona] | 3/5 issues | [date] |
 ```
 ## Inheritance Rules
 - **Personas**: Product personas extend org personas with product-specific context
 - **Jobs**: Product jobs trace back to org-level jobs (show the connection)
 - **Beliefs**: Inherited from manifesto, never duplicated in vision
 - **Principles**: Product adds specific principles that extend org principles
 - **Non-Goals**: Product adds its own; org non-goals apply automatically
 ## Guidelines
 - Product vision builds on organization manifesto - extend, don't duplicate
 - Every product persona should reference which org persona it extends
 - Every product job should show which org job it enables
 - Product principles should note which org principle they extend
 - Use `/manifesto` for organization-level identity and beliefs
 - Use `/vision` for product-specific direction and goals
--- a/commands/work-issue.md
+++ b/commands/work-issue.md
@@ -7,7 +7,7 @@ argument-hint: <issue-number>
@~/.claude/skills/gitea/SKILL.md
-1. **View the issue** to understand requirements
+1. **View the issue** with `--comments` flag to understand requirements and context
 2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
 3. **Plan**: Use TodoWrite to break down the work based on acceptance criteria
 4. **Implement** the changes
--- a/docs/writing-agents.md
+++ b/docs/writing-agents.md
@@ -67,6 +67,90 @@ All sections are important:
 - **When to Use**: Prevents misuse and guides selection
 - **Behavior**: Sets expectations for operation
 ## YAML Frontmatter
 Agent files support YAML frontmatter for configuration. While the body content defines the agent's personality and instructions, frontmatter controls its technical behavior.
 ### Required Fields
 | Field | Description |
 |-------|-------------|
 | `name` | Agent identifier (lowercase, hyphens). Should match directory name. |
 | `description` | What the agent does. Used for matching when spawning agents. |
 ### Optional Fields
 | Field | Description |
 |-------|-------------|
 | `model` | Model to use: `haiku`, `sonnet`, `opus`, or `inherit` (default). |
 | `skills` | Comma-separated list of skills the agent can access. |
 | `disallowedTools` | Explicitly block specific tools from this agent. |
 | `permissionMode` | Permission behavior: `default`, `bypassPermissions`, or custom. |
 | `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this agent. |
 ### Example Frontmatter
 **Basic agent:**
 ```yaml
 ---
 name: code-reviewer
 description: Review code for quality, bugs, and style issues.
 model: sonnet
 skills: gitea, code-review
 ---
 ```
 **Agent with tool restrictions:**
 ```yaml
 ---
 name: read-only-analyst
 description: Analyze code without making changes.
 model: haiku
 skills: code-review
 disallowedTools:
  - Edit
  - Write
  - Bash
 ---
 ```
 **Agent with hooks:**
 ```yaml
 ---
 name: database-admin
 description: Manage database operations safely.
 model: opus
 hooks:
  - type: PreToolUse
    matcher: Bash
    command: echo "Validating database command..."
  - type: Stop
    command: echo "Database operation completed"
 ---
 ```
 ### Permission Modes
 The `permissionMode` field controls how the agent handles tool permissions:
 | Mode | Behavior |
 |------|----------|
 | `default` | Inherits parent's permission settings (standard behavior) |
 | `bypassPermissions` | Skip permission prompts (use for trusted, well-tested agents) |
 Use `bypassPermissions` sparingly—only for agents that are thoroughly tested and operate within safe boundaries.
 ## Built-in Agents
 Claude Code provides built-in agents that you can leverage instead of creating custom ones:
 | Agent | Purpose | When to Use |
 |-------|---------|-------------|
 | **Explore** | Codebase exploration and search | Finding files, understanding structure, searching code. Powered by Haiku for efficiency. |
 | **Plan** | Implementation planning | Designing approaches, breaking down tasks, architectural decisions. |
 Consider using built-in agents before creating custom ones—they're optimized for common tasks.
 ## How Agents Combine Skills
 Agents gain their expertise by combining multiple skills. Each skill contributes domain knowledge to the agent's overall capability.
@@ -187,6 +271,28 @@ Agents can explore codebases independently, building understanding without pollu
 - Exploration might involve many file reads and searches
 - Results should be summarized, not shown in full
 ### 5. Background Execution
 Agents can run in the background while you continue working. Background agents execute asynchronously and notify the main thread when complete.
 ```
 User working                    Background Agent
 ┌─────────────────┐            ┌─────────────────┐
 │ Continue coding │            │ Running tests   │
 │ on feature      │            │ in background   │
 │                 │            │                 │
 │ (not blocked)   │   notify   │ (async work)    │
 │                 │ ◄───────── │                 │
 └─────────────────┘            └─────────────────┘
 ```
 **Use when:**
 - Task is long-running (test suites, large codebase analysis)
 - You want to continue working while the agent operates
 - Results are needed later, not immediately
 Background agents can send messages to wake up the main agent when they have results or need attention.
 ## When to Use an Agent vs Direct Skill Invocation
 ### Use Direct Skill Invocation When:
@@ -573,14 +679,26 @@ Improve based on usage:
 ## Checklist: Before Submitting a New Agent
 ### Structure
 - [ ] File is at `agents/<name>/AGENT.md`
 - [ ] Name follows kebab-case convention
 - [ ] Agent has a clear, recognizable role
- [ ] Skills list is deliberate (not too many, not too few)
+
- [ ] Model selection is deliberate (not just `inherit` by default)
+### Frontmatter
 - [ ] `name` and `description` fields are set
 - [ ] `model` selection is deliberate (not just `inherit` by default)
 - [ ] `skills` list is deliberate (not too many, not too few)
 - [ ] Consider `disallowedTools` if agent should be restricted
 - [ ] Consider `permissionMode` for trusted agents
 - [ ] Consider `hooks` for validation or logging
 ### Content
 - [ ] Capabilities are specific and achievable
 - [ ] "When to Use" guidance is clear
 - [ ] Behavioral rules prevent problems
 ### Integration
 - [ ] Consider if built-in agents (Explore, Plan) could be used instead
 - [ ] Agent is referenced by at least one command
 - [ ] ARCHITECTURE.md is updated
--- a/docs/writing-commands.md
+++ b/docs/writing-commands.md
@@ -43,10 +43,21 @@ argument-hint: <required-arg> [optional-arg]
 ---
 ```
-| Field | Purpose | Required |
+#### Required Fields
-|-------|---------|----------|
+
-| `description` | One-line summary for help/listings | Yes |
+| Field | Purpose |
-| `argument-hint` | Shows expected arguments | If arguments needed |
+|-------|---------|
 | `description` | One-line summary for help/listings |
 #### Optional Fields
 | Field | Purpose |
 |-------|---------|
 | `argument-hint` | Shows expected arguments (e.g., `<issue-number>`, `[title]`) |
 | `model` | Model to use: `haiku`, `sonnet`, `opus`. Overrides session default. |
 | `context` | Execution context. Use `fork` to run in isolated sub-agent context. |
 | `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this command. |
 | `allowed-tools` | Restrict which tools the command can use. |
 ### 2. Body (Markdown Instructions)
@@ -83,6 +94,50 @@ argument-hint: <issue-number>
 7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
 ```
 ## Advanced Frontmatter Examples
 **Command with specific model:**
 ```yaml
 ---
 description: Plan complex feature implementation.
 argument-hint: <feature-description>
 model: opus
 ---
 ```
 **Command with isolated context (prevents context pollution):**
 ```yaml
 ---
 description: Analyze codebase architecture deeply.
 context: fork
 model: haiku
 ---
 ```
 **Command with hooks:**
 ```yaml
 ---
 description: Deploy to production environment.
 hooks:
  - type: PreToolUse
    matcher: Bash
    command: echo "Validating deployment command..."
  - type: Stop
    command: ./scripts/notify-deployment.sh
 ---
 ```
 **Read-only command with tool restrictions:**
 ```yaml
 ---
 description: Generate codebase report without modifications.
 allowed-tools:
  - Read
  - Glob
  - Grep
 ---
 ```
 ## Argument Handling
 Commands can accept arguments from the user. Arguments are passed via positional variables: `$1`, `$2`, etc.
@@ -643,16 +698,29 @@ Update references:
 ## Checklist: Before Submitting a New Command
 ### Structure
 - [ ] File is at `commands/<name>.md`
 - [ ] Name follows kebab-case verb convention
- [ ] Frontmatter includes description
+
- [ ] Frontmatter includes argument-hint (if arguments needed)
+### Frontmatter (Required)
 - [ ] `description` is set with clear one-line summary
 - [ ] `argument-hint` is set (if command takes arguments)
 ### Frontmatter (Consider)
 - [ ] `model` if command benefits from specific model (e.g., `opus` for complex planning)
 - [ ] `context: fork` if command does heavy exploration that would pollute context
 - [ ] `allowed-tools` if command should be restricted to certain tools
 - [ ] `hooks` if command needs validation or post-execution actions
 ### Content
 - [ ] Workflow steps are clear and numbered
 - [ ] Commands and tools are specified explicitly
 - [ ] Skills are included via `@~/.claude/skills/<name>/SKILL.md` file references
 - [ ] Approval points exist before significant actions
 - [ ] Edge cases are handled (no data, invalid input)
 - [ ] Output formatting is specified
 ### Integration
 - [ ] ARCHITECTURE.md is updated with new command
 ## See Also
--- a/docs/writing-skills.md
+++ b/docs/writing-skills.md
@@ -29,8 +29,12 @@ Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude d
 | Field | Description |
 |-------|-------------|
-| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. |
+| `allowed-tools` | **Restricts** which tools Claude can use when this skill is active. If omitted, no restrictions apply. Supports YAML-style lists. |
-| `model` | Specific model to use when skill is active (e.g., `claude-sonnet-4-20250514`). |
+| `model` | Specific model to use when skill is active (e.g., `sonnet`, `opus`, `haiku`). |
 | `user-invocable` | Whether the skill appears in the `/` command menu. Defaults to `true`. Set to `false` for reference-only skills. |
 | `context` | Execution context. Use `fork` to run skill in an isolated sub-agent context, preventing context pollution. |
 | `agent` | Agent type to use for execution. Allows skills to specify which agent handles them. |
 | `hooks` | Define PreToolUse, PostToolUse, or Stop hooks scoped to this skill's lifecycle. |
 ### Writing Effective Descriptions
@@ -55,6 +59,7 @@ description: View, create, and manage Gitea issues and pull requests using tea C
 ---
 name: gitea
 description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, or when the user mentions tea, gitea, or issue numbers.
 user-invocable: false
 ---
 # Gitea CLI (tea)
@@ -62,6 +67,51 @@ description: View, create, and manage Gitea issues and pull requests using tea C
 [Rest of skill content...]
 ```
 ### Advanced Frontmatter Examples
 **Reference skill (not directly invocable):**
 ```yaml
 ---
 name: gitea
 description: CLI reference for Gitea operations.
 user-invocable: false
 ---
 ```
 **Skill with isolated context:**
 ```yaml
 ---
 name: codebase-analysis
 description: Deep codebase exploration and analysis.
 context: fork
 model: haiku
 ---
 ```
 **Skill with tool restrictions (YAML-style list):**
 ```yaml
 ---
 name: read-only-review
 description: Code review without modifications.
 allowed-tools:
  - Read
  - Glob
  - Grep
 ---
 ```
 **Skill with hooks:**
 ```yaml
 ---
 name: database-operations
 description: Database schema and migration operations.
 hooks:
  - type: PreToolUse
    matcher: Bash
    command: echo "Validating database command..."
 ---
 ```
 ## Subagents and Skills
 Subagents **do not automatically inherit skills** from the main conversation. To give a subagent access to skills, list them in the agent's `skills` field:
@@ -153,6 +203,14 @@ Skills are **model-invoked**: Claude decides which skills to use based on your r
 2. **On request**: Claude matches your request against skill descriptions using semantic similarity
 3. **Activation**: When a match is found, Claude asks to use the skill before loading the full content
 ### Hot Reload
 Skills support **automatic hot-reload**. When you create or modify a skill file in `~/.claude/skills/` or `.claude/skills/`, the changes are immediately available without restarting Claude Code. This enables rapid iteration when developing skills.
 ### Visibility in Command Menu
 By default, skills in `/skills/` directories appear in the `/` slash command menu. Users can invoke them directly like commands. To hide a skill from the menu (e.g., for reference-only skills), add `user-invocable: false` to the frontmatter.
 ### Subagent Access
 Subagents (defined in `.claude/agents/`) must explicitly list which skills they can use:
@@ -493,6 +551,13 @@ Keep skills current:
 - [ ] `description` lists specific capabilities
 - [ ] `description` includes "Use when..." with trigger terms
 ### Optional Frontmatter (Consider)
 - [ ] `user-invocable: false` if skill is reference-only (e.g., CLI docs)
 - [ ] `context: fork` if skill does heavy exploration that would pollute context
 - [ ] `model` if skill benefits from a specific model (e.g., `haiku` for speed)
 - [ ] `allowed-tools` if skill should be restricted to certain tools
 - [ ] `hooks` if skill needs validation or logging
 ### File Structure
 - [ ] File is at `skills/<name>/SKILL.md`
 - [ ] Name follows kebab-case convention
--- a/learnings/README.md
+++ b/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`
--- a/manifesto.md
+++ b/manifesto.md
@@ -0,0 +1,94 @@
 # Manifesto
 ## Who We Are
 We are a small, focused team building tools that make work easier. We believe software should support business processes without requiring everyone to become a developer. We build in public - sharing our AI-augmented development practices, tools, and learnings with the developer community.
 ## Who We Serve
 ### Domain Experts
 Business analysts, operations managers, process owners - people who understand their domain deeply but shouldn't need to code. They want to create and evolve software solutions that support their processes directly, without waiting for IT or hiring developers.
 ### Agencies & Consultancies
 Teams building solutions for clients using our platform. They need speed, consistency, and the ability to deliver maintainable solutions across engagements. Every efficiency gain multiplies across projects.
 ### Organizations
 From small businesses to enterprises - any organization that needs maintainable software to support their business processes. They benefit from solutions built on our platform, whether created by their own domain experts or by agencies on their behalf.
 ## What They're Trying to Achieve
 - "Help me create software that supports my business process without learning to code"
 - "Help me evolve my solutions as my business changes"
 - "Help me deliver maintainable solutions to clients faster"
 - "Help me get software that actually fits how we work"
 - "Help me reduce dependency on developers for business process changes"
 ## What We Believe
 ### Empowering Domain Experts
 We believe the people closest to business problems should be able to solve them:
 - **Domain expertise matters most.** The person who understands the process deeply is better positioned to design the solution than a developer translating requirements.
 - **Low-code removes barriers.** When domain experts can create and evolve solutions directly, organizations move faster and get better-fitting software.
 - **Maintainability enables evolution.** Business processes change. Software that supports them must be easy to adapt without starting over.
 - **Technology should disappear.** The best tools get out of the way. Domain experts should think about their processes, not about technology.
 ### AI-Augmented Development
 We believe AI fundamentally changes how software is built:
 - **Developers become orchestrators.** The role shifts from writing every line to directing, reviewing, and refining. The human provides judgment, context, and intent. AI handles execution and recall.
 - **Repetitive tasks should be automated.** If you do something more than twice, encode it. Commits, PR creation, issue management, code review - these should flow, not interrupt.
 - **AI amplifies individuals.** A solo developer with good AI tooling can accomplish what used to require a team. Small teams can tackle problems that used to need departments.
 - **Knowledge belongs in systems, not heads.** Best practices, patterns, and learnings should be encoded where AI can apply them. Tribal knowledge is a liability.
 - **Iteration speed is a competitive advantage.** The faster you can go from idea to deployed code to learning, the faster you improve. AI collapses the feedback loop.
 ### Quality Without Ceremony
 - Ship small, ship often
 - Automate verification, not just generation
 - Good defaults beat extensive configuration
 - Working software over comprehensive documentation
 ### Sustainable Pace
 - Tools should reduce cognitive load, not add to it
 - Automation should free humans for judgment calls
 - The goal is flow, not burnout
 ### Resource Efficiency
 - Software should run well on modest hardware
 - Cloud cost and energy consumption matter
 - ARM64-native where possible - better performance per watt
 - Bloated software is a sign of poor engineering, not rich features
 ## Guiding Principles
 1. **Encode, don't document.** If something is important enough to write down, it's important enough to encode into a skill, command, or agent that can act on it.
 2. **Small teams, big leverage.** Design for amplification. Every tool, pattern, and practice should multiply what individuals can accomplish.
 3. **Opinionated defaults, escape hatches available.** Make the right thing easy. Make customization possible but not required.
 4. **Learn in public.** Capture learnings. Update the system. Share what works.
 5. **Ship to learn.** Prefer shipping something imperfect and learning from reality over planning for perfection.
 ## Non-Goals
 - **Replacing human judgment.** AI and low-code tools augment human decision-making; they don't replace it. Domain expertise, critical thinking, and understanding of business context remain human responsibilities.
 - **Supporting every tool and platform.** We go deep on our chosen stack rather than shallow on everything.
 - **Building generic software.** We focus on maintainable solutions for business processes, not general-purpose applications.
 - **Comprehensive documentation for its own sake.** We encode knowledge into actionable systems. Docs exist to explain the "why," not to duplicate what the system already does.
--- a/repos.md
+++ b/repos.md
@@ -0,0 +1,71 @@
 # Repository Map
 Central registry of all Flowmade repositories.
 ## How to Use This
 Each repo's CLAUDE.md should reference this map for organization context. When working in any repo, Claude can check here to understand how it fits in the bigger picture.
 **Status markers:**
 - **Active** - Currently in use
 - **Splitting** - Being broken into smaller repos
 - **Planned** - Will be created (from split or new)
 ## Repositories
 ### Organization
 | Repo | Purpose | Status | Visibility |
 |------|---------|--------|------------|
 | architecture | Org source of truth: manifesto, Claude tooling, learnings | Active | Public |
 ### Platform
 | Repo | Purpose | Status | Visibility |
 |------|---------|--------|------------|
 | arcadia | Monorepo containing platform code | Splitting | Private |
 | aether | Event sourcing runtime with bytecode VM | Planned (from Arcadia) | Private |
 | iris | WASM UI framework | Planned (from Arcadia) | Public |
 | eskit | ES primitives (aggregates, events, projections, NATS) | Planned (from Arcadia) | Public |
 | adl | Domain language compiler | Planned (from Arcadia) | Private |
 | studio | Visual process designer, EventStorming tools | Planned (from Arcadia) | Private |
 ### Infrastructure
 | Repo | Purpose | Status | Visibility |
 |------|---------|--------|------------|
 | gitserver | K8s-native git server (proves ES/IRIS stack) | Planned | Public |
 ## Relationships
 ```
 arcadia (splitting into):
 ├── eskit (standalone, foundational)
 ├── iris (standalone)
 ├── aether (imports eskit)
 ├── adl (imports aether)
 └── studio (imports aether, iris, adl)
 gitserver (will use):
 ├── eskit (event sourcing)
 └── iris (UI)
 ```
 ## Open Source Strategy
 See [repo-conventions skill](skills/repo-conventions/SKILL.md) for classification criteria.
 **Open source** (public):
 - Generic libraries that benefit from community (eskit, iris)
 - Infrastructure tooling that builds awareness (gitserver)
 - Organization practices and tooling (architecture)
 **Proprietary** (private):
 - Core platform IP (aether VM, adl compiler)
 - Product features (studio)
 ## Related
 - [Manifesto](manifesto.md) - Organization identity and beliefs
 - [Issue #53](https://git.flowmade.one/flowmade-one/architecture/issues/53) - Git server proposal
 - [Issue #54](https://git.flowmade.one/flowmade-one/architecture/issues/54) - Arcadia split planning
--- a/skills/backlog-grooming/SKILL.md
+++ b/skills/backlog-grooming/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: backlog-grooming
 description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
 user-invocable: false
 ---
 # Backlog Grooming
@@ -33,10 +34,18 @@ For each issue, verify:
 - [ ] Clear boundaries (what's included/excluded)
 ### 5. Dependencies
- [ ] Dependencies identified
+- [ ] Dependencies identified in description
 - [ ] Dependencies formally linked (`tea issues deps list <number>`)
 - [ ] No circular dependencies
 - [ ] Blocking issues are tracked
 To check/fix dependencies:
 ```bash
 tea issues deps list <number>           # View current dependencies
 tea issues deps add <issue> <blocker>   # Add missing dependency
 tea issues deps remove <issue> <dep>    # Remove incorrect dependency
 ```
 ### 6. Labels
 - [ ] Type label (bug/feature/etc)
 - [ ] Priority if applicable
--- a/skills/claude-md-writing/SKILL.md
+++ b/skills/claude-md-writing/SKILL.md
@@ -0,0 +1,218 @@
 ---
 name: claude-md-writing
 description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
 user-invocable: false
 ---
 # Writing Effective CLAUDE.md Files
 CLAUDE.md is the project's context file for AI assistants. A good CLAUDE.md means Claude understands your project immediately without needing to explore.
 ## Purpose
 CLAUDE.md answers: "What does Claude need to know to work effectively in this repo?"
 - **Not a README** - README is for humans discovering the project
 - **Not documentation** - Docs explain how to use the product
 - **Context for AI** - What Claude needs to make good decisions
 ## Required Sections
 ### 1. One-Line Description
 Start with what this repo is in one sentence.
 ```markdown
 # Project Name
 Brief description of what this project does.
 ```
 ### 2. Organization Context
 Link to the bigger picture so Claude understands where this fits.
 ```markdown
 ## Organization Context
 This repo is part of Flowmade. See:
 - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
 - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
 - [Vision](./vision.md) - what this specific product does
 ```
 ### 3. Setup
 How to get the project running locally.
 ```markdown
 ## Setup
 \`\`\`bash
 # Clone and install
 git clone <url>
 cd <project>
 make install  # or npm install, etc.
 \`\`\`
 ```
 ### 4. Project Structure
 Key directories and what they contain. Focus on what's non-obvious.
 ```markdown
 ## Project Structure
 \`\`\`
 project/
 ├── cmd/           # Entry points
 ├── pkg/           # Shared packages
 │   ├── domain/    # Business logic
 │   └── infra/     # Infrastructure adapters
 ├── internal/      # Private packages
 └── api/           # API definitions
 \`\`\`
 ```
 ### 5. Development Commands
 The commands Claude will need to build, test, and run.
 ```markdown
 ## Development
 \`\`\`bash
 make build    # Build the project
 make test     # Run tests
 make lint     # Run linters
 make run      # Run locally
 \`\`\`
 ```
 ### 6. Architecture Decisions
 Key patterns and conventions specific to this repo.
 ```markdown
 ## Architecture
 ### Patterns Used
 - Event sourcing for state management
 - CQRS for read/write separation
 - Hexagonal architecture
 ### Conventions
 - All commands go through the command bus
 - Events are immutable value objects
 - Projections rebuild from events
 ```
 ## What Makes a Good CLAUDE.md
 ### Do Include
 - **Enough context to skip exploration** - Claude shouldn't need to grep around
 - **Key architectural patterns** - How the code is organized and why
 - **Non-obvious conventions** - Things that aren't standard
 - **Important dependencies** - External services, APIs, databases
 - **Common tasks** - How to do things Claude will be asked to do
 ### Don't Include
 - **Duplicated manifesto content** - Link to it instead
 - **Duplicated vision content** - Link to vision.md
 - **API documentation** - That belongs elsewhere
 - **User guides** - CLAUDE.md is for the AI, not end users
 - **Obvious things** - Don't explain what `go build` does
 ## Template
 ```markdown
 # [Project Name]
 [One-line description]
 ## Organization Context
 This repo is part of Flowmade. See:
 - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
 - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
 - [Vision](./vision.md) - what this specific product does
 ## Setup
 \`\`\`bash
 # TODO: Add setup instructions
 \`\`\`
 ## Project Structure
 \`\`\`
 project/
 ├── ...
 \`\`\`
 ## Development
 \`\`\`bash
 make build    # Build the project
 make test     # Run tests
 make lint     # Run linters
 \`\`\`
 ## Architecture
 ### Patterns
 - [List key patterns]
 ### Conventions
 - [List important conventions]
 ### Key Components
 - [Describe main components and their responsibilities]
 ```
 ## Examples
 ### Good: Enough Context
 ```markdown
 ## Architecture
 This service uses event sourcing. State is rebuilt from events, not stored directly.
 ### Key Types
 - `Aggregate` - Domain object that emits events
 - `Event` - Immutable fact that something happened
 - `Projection` - Read model built from events
 ### Adding a New Aggregate
 1. Create type in `pkg/domain/`
 2. Implement `HandleCommand()` and `ApplyEvent()`
 3. Register in `cmd/main.go`
 ```
 Claude can now work with aggregates without exploring the codebase.
 ### Bad: Too Vague
 ```markdown
 ## Architecture
 Uses standard Go patterns. See the code for details.
 ```
 Claude has to explore to understand anything.
 ## Maintenance
 Update CLAUDE.md when:
 - Adding new architectural patterns
 - Changing project structure
 - Adding important dependencies
 - Discovering conventions that aren't documented
 Don't update for:
 - Every code change
 - Bug fixes
 - Minor refactors
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: code-review
 description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
 user-invocable: false
 ---
 # Code Review
--- a/skills/gitea/SKILL.md
+++ b/skills/gitea/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: gitea
 description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
 user-invocable: false
 ---
 # Gitea CLI (tea)
@@ -70,6 +71,13 @@ tea issues reopen <number>
 # Labels
 tea issues edit <number> --labels "bug,help wanted"
 # Dependencies
 tea issues deps list <number>              # List blockers for an issue
 tea issues deps add <issue> <blocker>      # Add dependency (issue is blocked by blocker)
 tea issues deps add 5 3                    # Issue #5 depends on #3
 tea issues deps add 5 owner/repo#3         # Cross-repo dependency
 tea issues deps remove <issue> <blocker>   # Remove a dependency
 ```
 ### Pull Requests
--- a/skills/issue-writing/SKILL.md
+++ b/skills/issue-writing/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: issue-writing
 description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
 user-invocable: false
 ---
 # Issue Writing
@@ -48,6 +49,39 @@ Examples:
 - [ ] Session persists across browser refresh
 ```
 ## Vertical Slices
 Issues should be **vertical slices** that deliver user-visible value.
 ### The Demo Test
 Before writing an issue, ask: **Can a user demo or test this independently?**
 - **Yes** → Good issue scope
 - **No** → Rethink the breakdown
 ### Good vs Bad Issue Titles
 | Good (Vertical) | Bad (Horizontal) |
 |-----------------|------------------|
 | "User can save and reload diagram" | "Add persistence layer" |
 | "Show error when login fails" | "Add error handling" |
 | "Domain expert can list orders" | "Add query syntax to ADL" |
 ### Writing User-Focused Issues
 Frame issues around user capabilities:
 ```markdown
 # Bad: Technical task
 Title: Add email service integration
 # Good: User capability
 Title: User receives confirmation email after signup
 ```
 The technical work is the same, but the good title makes success criteria clear.
 ## Issue Types
 ### Bug Report
@@ -104,7 +138,19 @@ Use labels to categorize:
 ## Dependencies
-Reference related issues:
+Identify and link dependencies when creating issues:
- "Depends on #N" - Must complete first
+
- "Blocks #N" - This blocks another
+1. **In the description**, document dependencies:
- "Related to #N" - Informational link
+   ```markdown
   ## Dependencies
   - Depends on #12 (must complete first)
   - Related to #15 (informational)
   ```
 2. **After creating the issue**, formally link blockers using tea CLI:
   ```bash
   tea issues deps add <this-issue> <blocker-issue>
   tea issues deps add 5 3    # Issue #5 is blocked by #3
   ```
 This creates a formal dependency graph that tools can query.
--- a/skills/repo-conventions/SKILL.md
+++ b/skills/repo-conventions/SKILL.md
@@ -0,0 +1,204 @@
 ---
 name: repo-conventions
 description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
 user-invocable: false
 ---
 # Repository Conventions
 Standard structure and conventions for Flowmade repositories.
 ## Repository Layout
 All product repos should follow this structure relative to the architecture repo:
 ```
 org/
 ├── architecture/           # Organizational source of truth
 │   ├── manifesto.md        # Organization identity and beliefs
 │   ├── commands/           # Claude Code workflows
 │   ├── skills/             # Knowledge modules
 │   └── agents/             # Subtask handlers
 ├── product-a/              # Product repository
 │   ├── vision.md           # Product vision (extends manifesto)
 │   ├── CLAUDE.md           # AI assistant instructions
 │   ├── .gitea/workflows/   # CI/CD pipelines
 │   └── ...
 └── product-b/
    └── ...
 ```
 ## Required Files
 ### vision.md
 Every product repo needs a vision that extends the organization manifesto.
 ```markdown
 # Vision
 This product vision builds on the [organization manifesto](../architecture/manifesto.md).
 ## Who This Product Serves
 ### [Persona Name]
 [Product-specific description]
 *Extends: [Org persona] (from manifesto)*
 ## What They're Trying to Achieve
 | Product Job | Enables Org Job |
 |-------------|-----------------|
 | "[Product job]" | "[Org job from manifesto]" |
 ## The Problem
 [Pain points this product addresses]
 ## The Solution
 [How this product solves those problems]
 ## Product Principles
 ### [Principle Name]
 [Description]
 *Extends: "[Org principle]"*
 ## Non-Goals
 - **[Non-goal].** [Explanation]
 ```
 ### CLAUDE.md
 Project-specific context for AI assistants. See [claude-md-writing skill](../claude-md-writing/SKILL.md) for detailed guidance.
 ```markdown
 # [Project Name]
 [One-line description]
 ## Organization Context
 This repo is part of Flowmade. See:
 - [Organization manifesto](../architecture/manifesto.md) - who we are, what we believe
 - [Repository map](../architecture/repos.md) - how this fits in the bigger picture
 - [Vision](./vision.md) - what this specific product does
 ## Setup
 [How to get the project running locally]
 ## Project Structure
 [Key directories and their purposes]
 ## Development
 [How to build, test, run]
 ## Architecture
 [Key architectural decisions and patterns]
 ```
 ### .gitea/workflows/ci.yaml
 Standard CI pipeline. Adapt based on language/framework.
 ```yaml
 name: CI
 on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: make build
      - name: Test
        run: make test
      - name: Lint
        run: make lint
 ```
 ## Naming Conventions
 ### Repository Names
 - Lowercase with hyphens: `product-name`, `service-name`
 - Descriptive but concise
 - No prefixes like `flowmade-` (the org already provides context)
 ### Branch Names
 - `main` - default branch, always deployable
 - `issue-<number>-<short-description>` - feature branches
 - No `develop` or `staging` branches - use main + feature flags
 ### Commit Messages
 - Imperative mood: "Add feature" not "Added feature"
 - First line: summary (50 chars)
 - Body: explain why, not what (the diff shows what)
 - Reference issues: "Fixes #42" or "Closes #42"
 ## Open vs Proprietary
 Decisions about what to open-source are guided by the manifesto:
 | Type | Open Source? | Reason |
 |------|--------------|--------|
 | Infrastructure tooling | Yes | Builds community, low competitive risk |
 | Generic libraries | Yes | Ecosystem benefits, adoption |
 | Core platform IP | No | Differentiator, revenue source |
 | Domain-specific features | No | Product value |
 When uncertain, default to proprietary. Opening later is easier than closing.
 ## CI/CD Conventions
 ### Runners
 - Use self-hosted ARM64 runners where possible (resource efficiency)
 - KEDA-scaled runners for burst capacity
 - Cache dependencies aggressively
 ### Deployments
 - Main branch auto-deploys to staging
 - Production requires manual approval or tag
 - Use GitOps (ArgoCD) for Kubernetes deployments
 ## Dependencies
 ### Go Projects
 - Use Go modules
 - Vendor dependencies for reproducibility
 - Pin major versions, allow minor updates
 ### General
 - Prefer fewer, well-maintained dependencies
 - Audit transitive dependencies
 - Update regularly, don't let them rot
 ## Documentation
 Following the manifesto principle "Encode, don't document":
 - CLAUDE.md: How to work with this repo (for AI and humans)
 - vision.md: Why this product exists
 - Code comments: Only for non-obvious "why"
 - No separate docs folder unless user-facing documentation
--- a/skills/roadmap-planning/SKILL.md
+++ b/skills/roadmap-planning/SKILL.md
@@ -1,6 +1,7 @@
 ---
 name: roadmap-planning
 description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
 user-invocable: false
 ---
 # Roadmap Planning
@@ -32,6 +33,48 @@ How to plan features and create issues for implementation.
 - Reference dependencies explicitly
 - Use consistent labeling
 ## Vertical vs Horizontal Slices
 **Prefer vertical slices** - each issue should deliver user-visible value.
 | Vertical (Good) | Horizontal (Bad) |
 |-----------------|------------------|
 | "User can save and reload their diagram" | "Add persistence layer" + "Add save API" + "Add load API" |
 | "Domain expert can list all orders" | "Add query syntax to ADL" + "Add query runtime" + "Add query UI" |
 | "User can reset forgotten password" | "Add email service" + "Add reset token model" + "Add reset form" |
 ### The Demo Test
 Ask: **Can a user demo or test this issue independently?**
 - **Yes** → Good vertical slice
 - **No** → Probably a horizontal slice, break differently
 ### Break by User Capability, Not Technical Layer
 Instead of thinking "what technical components do we need?", think "what can the user do after this issue is done?"
 ```
 # Bad: Technical layers
 ├── Add database schema
 ├── Add API endpoint
 ├── Add frontend form
 # Good: User capabilities
 ├── User can create a draft
 ├── User can publish the draft
 ├── User can edit published content
 ```
 ### When Horizontal Slices Are Acceptable
 Sometimes horizontal slices are necessary:
 - **Infrastructure setup** - Database, CI/CD, deployment (do once, enables everything)
 - **Security foundations** - Auth system before any protected features
 - **Shared libraries** - When multiple features need the same foundation
 Even then, keep them minimal and follow immediately with vertical slices that use them.
 ## Breaking Down Features
 ### By Layer
@@ -80,6 +123,13 @@ In issue descriptions:
 - Depends on #13 (API setup)
 ```
 After creating issues, formally link dependencies:
 ```bash
 tea issues deps add <issue> <blocker>
 tea issues deps add 14 12    # Issue #14 depends on #12
 tea issues deps add 14 13    # Issue #14 depends on #13
 ```
 ## Creating Issues
 Use the gitea skill for issue operations.
--- a/skills/vision-management/SKILL.md
+++ b/skills/vision-management/SKILL.md
@@ -0,0 +1,272 @@
 ---
 name: vision-management
 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.
 user-invocable: false
 ---
 # Vision Management
 How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
 ## Architecture
 | Level | Document | Purpose | Command | Location |
 |-------|----------|---------|---------|----------|
 | **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | `../architecture/` (sibling repo) |
 | **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repo root |
 | **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
 Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
 ---
 ## Manifesto (Organization Level)
 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
 This product vision builds on the [organization manifesto](../architecture/manifesto.md).
 ## Who This Product Serves
 ### [Persona Name]
 [Product-specific description]
 *Extends: [Org persona] (from manifesto)*
 ## What They're Trying to Achieve
 These trace back to organization-level jobs:
 | Product Job | Enables Org Job |
 |-------------|-----------------|
 | "[Product-specific job]" | "[Org job from manifesto]" |
 ## The Problem
 [Pain points this product addresses]
 ## The Solution
 [How this product solves those problems]
 ## Product Principles
 These extend the organization's guiding principles:
 ### [Principle Name]
 [Description]
 *Extends: "[Org principle]"*
 ## Non-Goals
 These extend the organization's non-goals:
 - **[Non-goal].** [Explanation]
 ```
 ### When to Update Vision
 - When product direction shifts
 - When adding/changing personas served by this product
 - When discovering new non-goals
 - After major learnings from retros
 ### Creating a Product Vision
 1. **Start with the manifesto** - read it first
 2. Define product personas that extend org personas
 3. Identify product jobs that trace back to org jobs
 4. Articulate the problem this product solves
 5. Define the solution approach
 6. Set product-specific principles (noting what they extend)
 7. Document product non-goals
 8. Create initial milestones
 ---
 ## Inheritance Model
 ```
 Manifesto (org)              Vision (product)
 ├── Personas            →    Product Personas (extend with specifics)
 ├── Jobs                →    Product Jobs (trace back to org jobs)
 ├── Beliefs             →    (inherited, never duplicated)
 ├── Principles          →    Product Principles (extend, note source)
 └── Non-Goals           →    Product Non-Goals (additive)
 ```
 ### Inheritance Rules
 | Component | Rule | Format |
 |-----------|------|--------|
 | **Personas** | Extend with product-specific context | `*Extends: [Org persona] (from manifesto)*` |
 | **Jobs** | Trace back to org-level jobs | Table with Product Job → Org Job columns |
 | **Beliefs** | Inherited automatically | Never include in vision |
 | **Principles** | Add product-specific, note what they extend | `*Extends: "[Org principle]"*` |
 | **Non-Goals** | Additive | Org non-goals apply automatically |
 ### Example
 **Manifesto** (organization):
 ```markdown
 ## Who We Serve
 - **Agencies & Consultancies**: Teams building solutions for clients
 ```
 **Vision** (product - architecture tooling):
 ```markdown
 ## Who This Product Serves
 ### Flowmade Developers
 The team building Flowmade's platform. They need efficient, consistent AI workflows.
 *Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
 ```
 The product persona extends the org persona with product-specific context and explicitly notes the connection.
 ---
 ## 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)
 - Include success criteria in description
 ```bash
 tea milestones create --title "Automate routine git workflows" \
  --description "For: Solo developer
 Job: Ship without context switching to git commands
 Success: /commit and /pr commands handle 80% of workflows"
 ```
 ### Milestone-to-Vision Alignment
 Every milestone should trace to:
 - A persona (from vision, which extends manifesto)
 - A job to be done (from vision, which traces to manifesto)
 - A measurable outcome
 ---
 ## Aligning Issues with Vision
 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 milestone alignment**: Does this issue support a goal?
 4. **Assign to milestone**: Link the issue to the relevant goal
 Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
 ### Identifying Gaps
 - **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?
 - **Orphan issues**: Issues without a milestone need justification
 ---
 ## Continuous Improvement Loop
 ```
 Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
                                                    ↓
                                          Architecture repo issues
                                                    ↓
                                          Encoded into learnings +
                                          skills/commands/agents
 ```
 1. **Manifesto** defines organizational identity (very stable)
 2. **Vision** defines product direction, extends manifesto (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
 ---
 ## Quick Reference
 | Question | Answer |
 |----------|--------|
 | Where do shared personas live? | `manifesto.md` in architecture repo |
 | Where do product personas live? | `vision.md` in product repo (extend org personas) |
 | Where do beliefs live? | `manifesto.md` only (inherited, never duplicated) |
 | 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 |
 | How do product jobs relate to org jobs? | They trace back (show in table) |
 | How do product principles relate? | They extend (note the source) |
Author	SHA1	Message	Date
Hugo Nijhuis	65a107c2eb	Add vertical vs horizontal slicing guidance Adds guidance to prefer vertical slices (user-visible value) over horizontal slices (technical layers) when planning and writing issues. roadmap-planning skill: - New "Vertical vs Horizontal Slices" section - Demo test: "Can a user demo/test this independently?" - Good vs bad examples table - When horizontal slices are acceptable issue-writing skill: - New "Vertical Slices" section - Demo test guidance - Good vs bad issue titles table - User-focused issue framing examples Closes #31 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-09 13:21:52 +01:00
Hugo Nijhuis	ff56168073	Mark skills as not user-invocable Skills are knowledge modules referenced by commands, not directly invoked by users. Added user-invocable: false to: - backlog-grooming (used by /groom) - claude-md-writing (used by /update-claude-md) - code-review (used by /review-pr) - issue-writing (used by /create-issue) - roadmap-planning (used by /plan-issues) - vision-management (used by /vision, /manifesto) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-09 13:01:19 +01:00
Hugo Nijhuis	d980a0d0bc	Add new frontmatter fields from Claude Code 2.1.0 Update documentation and apply new frontmatter capabilities: Documentation: - Add user-invocable, context, agent, hooks fields to writing-skills.md - Add disallowedTools, permissionMode, hooks fields to writing-agents.md - Add model, context, hooks, allowed-tools fields to writing-commands.md - Document skill hot-reload, built-in agents, background execution Skills: - Add user-invocable: false to gitea (CLI reference) - Add user-invocable: false to repo-conventions (standards reference) Commands: - Add context: fork to heavy exploration commands (improve, plan-issues, create-repo, update-claude-md) - Add missing argument-hint to roadmap, manifesto, improve Agents: - Add disallowedTools: [Edit, Write] to code-reviewer for safety Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-08 14:19:56 +01:00
Hugo Nijhuis	1f1d9961fc	Add /update-claude-md command Updates or creates CLAUDE.md with: - Organization context section (links to manifesto, repos.md, vision) - Current project structure from filesystem scan - Architecture patterns inferred or asked Preserves existing custom content, shows diff before writing. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-08 10:26:10 +01:00
Hugo Nijhuis	057d4dac57	Add CLAUDE.md guidance and repository map - Create claude-md-writing skill with best practices for CLAUDE.md files - Create repos.md registry of all repos with status (Active/Planned/Splitting) - Update /create-repo to include organization context section - Update repo-conventions to reference new skill Each repo's CLAUDE.md now links to manifesto, repos.md, and vision.md so Claude always understands the bigger picture. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-08 10:24:10 +01:00
Hugo Nijhuis	0e1a65f0e3	Add repo-conventions skill and /create-repo command Skill documents standard repo structure, naming conventions, open vs proprietary guidance, and CI/CD patterns. Command scaffolds new repos with vision.md, CLAUDE.md, Makefile, CI workflow, and .gitignore - all linked to the architecture repo. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 23:58:16 +01:00
Hugo Nijhuis	305e4b8927	Add resource efficiency belief to manifesto Software should run well on modest hardware. ARM64-native where possible. Bloated software is a sign of poor engineering. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 23:50:07 +01:00
Hugo Nijhuis	1dff275479	Use sibling repo convention for manifesto location Product repos find the manifesto at ../architecture/manifesto.md. This allows the architecture repo to be a sibling of product repos. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 22:21:31 +01:00
Hugo Nijhuis	c88304a271	Update vision system to properly extend manifesto - Rebuild vision.md to trace personas, jobs, and principles back to manifesto - Improve /vision command with inheritance guidance and templates - Update vision-management skill with explicit inheritance rules and formats Product visions now explicitly extend (not duplicate) organization manifesto. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 22:14:25 +01:00
Hugo Nijhuis	a3056bce12	Refocus manifesto on domain experts and organizations Shift from developer-centric personas (solo dev, small team) to the actual mission: empowering domain experts to create software without coding. - Who We Serve: Domain experts, Agencies, Organizations (small → enterprise) - Added "Empowering Domain Experts" beliefs section - Integrated "build in public" into Who We Are - Updated non-goals to align with new focus 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 21:33:25 +01:00
Hugo Nijhuis	f1c555706b	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>	2026-01-07 20:55:06 +01:00
Hugo Nijhuis	dc7b554ee6	Update vision-management skill for manifesto vs vision distinction Restructured skill to clearly distinguish: - Manifesto: Organization-level (architecture repo) - Vision: Product-level (product repos) Key additions: - Architecture table showing all three levels with commands - Manifesto section with structure, when to update, creation steps - Vision section clarified as product-level extending manifesto - Relationship diagram showing inheritance model - Example of persona inheritance (org → product) - Continuous improvement loop including retro → encoding flow - Quick reference table for common questions Closes #43 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:43:34 +01:00
Hugo Nijhuis	fac88cfcc7	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>	2026-01-07 20:38:29 +01:00
Hugo Nijhuis	8868eedc31	Update /retro command to store learnings and create encoding issues Restructured retro flow to: 1. Store learnings in learnings/ folder (historical + governance) 2. Create encoding issues to update skills/commands/agents 3. Cross-reference between learning files and issues 4. Handle both architecture and product repos differently Key changes: - Learning file template with Date, Context, Learning, Encoded In, Governance - Encoding issue template referencing the learning file - Encoding destinations table (skill/command/agent/manifesto/vision) - Clear guidance for architecture vs product repo workflows - Updated labels (learning instead of retrospective) Closes #42 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:27:29 +01:00
Hugo Nijhuis	c0ef16035c	Update /vision command for product-level only Clarifies /vision is for product-level vision, distinct from /manifesto which handles organization-level vision. Changes: - Added architecture table showing org vs product vs goals levels - Process now checks for manifesto first for org context - Output format includes Organization Context section - Guidelines clarify when to use /manifesto vs /vision - Product personas/jobs extend (not duplicate) org-level ones Closes #41 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:24:28 +01:00
Hugo Nijhuis	a8a35575b5	Create /manifesto command for organization vision Adds new command to view and manage the organization-level manifesto. Distinct from /vision which handles product-level vision. Features: - Guides manifesto creation if none exists - Displays formatted summary of existing manifesto - References vision-management skill - Clear output format for all sections Closes #40 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:20:28 +01:00
Hugo Nijhuis	fdf8a61077	Create learnings/ folder with structure and template Adds learnings folder for capturing insights from retros and daily work. Learnings serve as historical record, governance reference, and encoding source for skills/commands/agents. README includes: - Purpose explanation (historical + governance + encoding) - Learning template with all sections - Encoding process and destination guide - Periodic review guidance - Naming conventions Closes #39 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:17:31 +01:00
Hugo Nijhuis	c5c1a58e16	Create manifesto.md for organization vision Defines the foundational organization-level vision: - Who We Are: Small, focused AI-native builders - Personas: Solo developer, Small team, Agency/Consultancy - Jobs to Be Done: Ship fast, maintain quality, stay in flow - Beliefs: AI-augmented development, quality without ceremony, sustainable pace - Guiding Principles: Encode don't document, small teams big leverage, etc. - Non-Goals: Enterprise compliance, every platform, replacing judgment Closes #38 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 20:00:08 +01:00
Hugo Nijhuis	ae4e18feee	Add personas and jobs to be done to vision system The vision system now guides defining WHO we build for and WHAT they're trying to achieve before jumping into goals and issues. Updated vision-management skill: - New vision.md structure with Personas and Jobs to Be Done sections - Guidance for defining good personas (specific, characterized, limited) - Guidance for jobs to be done (outcome-focused, in their voice, pain-aware) - Milestones now tied to personas and jobs with structured descriptions - Issue alignment checks persona/job fit before milestone fit Updated vision command: - Guides through persona and JTBD definition when creating vision - Output format shows personas and jobs prominently - Guidelines emphasize traceability to personas Updated plan-issues command: - Identifies persona and job before breaking down work - Plan presentation includes For/Job/Supports context - Flags misalignment with persona/job, not just goals 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 17:52:17 +01:00
Hugo Nijhuis	1c0b6b3712	Add dependency management to issue workflows Updated skills and commands to identify and formally link issue dependencies using tea CLI: Skills updated: - issue-writing: Document deps in description + link with tea CLI - backlog-grooming: Check for formal dependency links in checklist - roadmap-planning: Link dependencies after creating issues Commands updated: - create-issue: Ask about and link dependencies for new issues - plan-issues: Create in dependency order, link with tea issues deps add - groom: Check dependency status, suggest missing links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 16:35:39 +01:00
Hugo Nijhuis	f50b0dacf3	Add issue dependencies documentation to gitea skill Documents the new tea CLI dependency management commands: - tea issues deps list - list blockers - tea issues deps add - add dependency (same or cross-repo) - tea issues deps remove - remove dependency 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-07 16:24:27 +01:00
Hugo Nijhuis	00bdd1deba	Include comments when viewing issues and PRs Updated work-issue and review-pr commands to use --comments flag, ensuring discussion context is available when working on issues or reviewing pull requests. Closes #32 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-06 12:59:27 +01:00
Hugo Nijhuis	e1ed17e2bf	Clarify agent architecture: small focused subtasks, not broad personas - Remove product-manager agent (too broad, not being used) - Update vision.md: agents are small, isolated, result-oriented - Update CLAUDE.md: add Architecture section explaining skills/commands/agents 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-01 22:49:42 +01:00
Hugo Nijhuis	28242d44cc	Use Gitea milestones for goal tracking instead of vision issue Refactored the vision system to separate concerns: - vision.md remains the stable "north star" philosophy document - Gitea milestones now track goals with automatic progress via issue counts - Updated /vision, /retro, and /create-issue commands to auto-assign milestones 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-01 22:22:06 +01:00
Hugo Nijhuis	9e1ca55196	Add vision-driven continuous improvement to product-manager Transforms the product-manager from a reactive backlog manager into a vision-driven system with continuous improvement capabilities. New components: - vision-management skill: How to create, maintain, and evolve product vision - /vision command: View, create, or update product vision (syncs to Gitea) - /improve command: Identify gaps between vision goals and backlog Enhanced existing components: - product-manager agent: Now vision-aware with strategic prioritization - /retro command: Connects learnings back to vision updates - /plan-issues command: Shows vision alignment for planned work The vision lives in two places: vision.md (source of truth) and a Gitea issue labeled "vision" for integration with the issue workflow. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-01 21:57:28 +01:00
Hugo Nijhuis	a2c77a338b	Add merging documentation to review-pr command - Document tea pulls merge as the correct merge method - Add warning against using Gitea API with admin credentials - Document tea comment as alternative to interactive tea pulls review 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-01 19:11:13 +01:00
Hugo Nijhuis	37a882915f	Remove separate approval step from code-reviewer agent The approval step was failing on self-authored PRs and stopping the merge flow. Since LGTM verdict already indicates approval, just merge directly without the separate tea pulls approve command. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-01 19:08:41 +01:00