Address review feedback: clarify approval gate before file creation

- Made step 11 explicitly a gate before file creation
- Added explicit conditional ("If user declines/approves") flow
- Added note at Phase 6 start: "Only execute this phase after user approval"
- Added error handling notes for directory creation and file writes

The step ordering was already correct (approval step 11 before file creation
steps 12-13), but the flow is now more explicit about the conditional nature.

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

CLAUDE.md

@@ -1,20 +1,36 @@
-# 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 |
+| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
+| `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
+├── software-architecture.md  # Patterns linked to beliefs (DDD, ES)
+├── learnings/                # Captured learnings and governance
 ├── commands/                 # Slash commands (/work-issue, /dashboard)
 ├── skills/         # Knowledge modules (auto-triggered)
 ├── agents/         # Focused subtask handlers (isolated context)
@@ -25,41 +41,28 @@ ai/
 
 All files symlink to `~/.claude/` via `make install`.
 
-## Architecture
+## Two Levels of Vision
 
-### Skills
+| Level | Document | Command | Purpose |
-Knowledge modules that teach Claude how to do something. Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`.
+|-------|----------|---------|---------|
+| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
+| Product | `vision.md` | `/vision` | Product-specific direction and goals |
 
-- **Purpose**: Encode best practices and tool knowledge
+See the manifesto for our identity, personas, and beliefs about AI-augmented development.
-- **Location**: `skills/<name>/SKILL.md`
-- **Usage**: Included in commands for context, auto-triggered by Claude Code
 
-Example: `gitea` skill teaches tea CLI usage, `issue-writing` teaches how to structure issues.
+## Available Commands
 
-### Commands
+| Command | Description |
-User-facing entry points invoked with `/command-name`. Run in main conversation context.
+|---------|-------------|
-
+| `/manifesto` | View/manage organization manifesto |
-- **Purpose**: Orchestrate workflows with user interaction
+| `/vision` | View/manage product vision and milestones |
-- **Location**: `commands/<name>.md`
+| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
-- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
+| `/dashboard` | Show open issues and PRs |
-
+| `/review-pr <n>` | Review PR with diff and comments |
-Commands reference skills for knowledge and optionally spawn agents for subtasks.
+| `/create-issue` | Create single or batch issues |
-
+| `/retro` | Capture learnings as issues for encoding |
-### Agents
+| `/plan-issues` | Break down features into issues |
-Small, focused units that handle specific subtasks in isolated context.
+| `/groom` | Improve issue quality |
-
-- **Purpose**: Complex subtasks that benefit from isolation
-- **Location**: `agents/<name>/agent.md`
-- **Usage**: Spawned via Task tool, return results to caller
-
-Good agent candidates:
-- Code review (analyze diff, report issues)
-- Content generation (write issue body, PR description)
-- Analysis tasks (categorize, prioritize, summarize)
-
-**When to use agents vs direct execution:**
-- Use agents when: task is self-contained, benefits from isolation, can run in parallel
-- Use direct execution when: task needs conversation history, requires user interaction mid-task
 
 ## Gitea Integration
 
@@ -73,19 +76,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, create improvement issues |
-| `/vision` | View/manage product vision and milestones |
-| `/plan-issues` | Break down features into issues |
-| `/improve` | Identify gaps between vision and backlog |
 
-## Vision & Goals
+- **Purpose**: Encode best practices and tool knowledge
+- **Location**: `skills/<name>/SKILL.md`
+- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
 
-Product vision lives in `vision.md` (philosophy) and Gitea milestones (goals with progress tracking). See `/vision` command.
+### Commands
+User-facing entry points invoked with `/command-name`.
+
+- **Purpose**: Orchestrate workflows with user interaction
+- **Location**: `commands/<name>.md`
+- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
+
+### Agents
+Focused units that handle specific subtasks in isolated context.
+
+- **Purpose**: Complex subtasks that benefit from isolation
+- **Location**: `agents/<name>/agent.md`
+- **Usage**: Spawned via Task tool, return results to caller
+
+### Learnings
+Captured insights from work, encoded into skills/commands/agents.
+
+- **Purpose**: Historical record + governance + continuous improvement
+- **Location**: `learnings/YYYY-MM-DD-title.md`
+- **Flow**: Retro → Issue → Encode into learning + system update

README.md

@@ -1,4 +1,6 @@
-# Claude Code AI Workflow
+# Architecture
+
+The organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.
 
 A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
 
@@ -53,8 +55,8 @@ The project is built around three composable component types:
 
 ```bash
 # Clone the repository
-git clone ssh://git@code.flowmade.one/flowmade-one/ai.git
+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

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,102 +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 are small, focused units that handle specific subtasks in isolated context.
-
-Unlike commands (which run in the main conversation), agents are spawned via the Task tool to do a specific job and report back. They should be:
-- **Small and focused**: One clear responsibility
-- **Isolated**: Work without needing conversation history
-- **Result-oriented**: Return a specific output (analysis, categorization, generated content)
-
-Examples:
-- `code-reviewer`: Reviews a PR diff and reports issues
-- A hypothetical `categorize-milestone`: Given an issue, determines which milestone it belongs to
-
-Agents enable:
-- **Parallel processing**: Multiple agents can work simultaneously
-- **Context isolation**: Complex subtasks don't pollute the main conversation
-- **Reusability**: Same agent can be spawned by different commands
-
-### 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. References skills for knowledge (how to write issues, use Gitea, etc.)
-3. Optionally spawns agents for complex subtasks
-4. Guides you through the workflow with approvals
-5. Takes action (creates issues, PRs, etc.)
-
-Commands run in the main conversation context, using skills for knowledge and spawning agents only when isolated processing is beneficial.
-
-## 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.

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,9 @@ 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**: Merge with `tea pulls merge <number> --style rebase`
+   - **WARNING**: Do NOT use heredoc syntax `$(cat <<'EOF'...)` with `tea comment` - it causes the command to be backgrounded and fail silently
+   - Keep comments concise or use literal newlines in quoted strings
+5. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`, then clean up with `tea pulls clean <number>`
 6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
 
 ## Review Comment Format

agents/issue-worker/agent.md

@@ -0,0 +1,130 @@
+---
+name: issue-worker
+description: Autonomous agent that implements a single issue in an isolated git worktree
+tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite
+skills: gitea, issue-writing, software-architecture
+---
+
+# Issue Worker Agent
+
+Autonomously implements a single issue in an isolated git worktree. Creates a PR and returns - the orchestrator handles review.
+
+## Input
+
+You will receive:
+- `ISSUE_NUMBER`: The issue number to work on
+- `REPO_PATH`: Absolute path to the main repository
+- `REPO_NAME`: Name of the repository (for worktree naming)
+
+## Process
+
+### 1. Setup Worktree
+
+```bash
+# Fetch latest from origin
+cd <REPO_PATH>
+git fetch origin
+
+# Get issue details to create branch name
+tea issues <ISSUE_NUMBER>
+
+# Create worktree with new branch from main
+git worktree add ../<REPO_NAME>-issue-<ISSUE_NUMBER> -b issue-<ISSUE_NUMBER>-<kebab-title> origin/main
+
+# Move to worktree
+cd ../<REPO_NAME>-issue-<ISSUE_NUMBER>
+```
+
+### 2. Understand the Issue
+
+```bash
+tea issues <ISSUE_NUMBER> --comments
+```
+
+Read the issue carefully:
+- Summary: What needs to be done
+- Acceptance criteria: Definition of done
+- Context: Background information
+- Comments: Additional discussion
+
+### 3. Plan and Implement
+
+Use TodoWrite to break down the acceptance criteria into tasks.
+
+Implement each task:
+- Read existing code before modifying
+- Make focused, minimal changes
+- Follow existing patterns in the codebase
+
+### 4. Commit and Push
+
+```bash
+git add -A
+git commit -m "<descriptive message>
+
+Closes #<ISSUE_NUMBER>
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+git push -u origin issue-<ISSUE_NUMBER>-<kebab-title>
+```
+
+### 5. Create PR
+
+```bash
+tea pulls create \
+  --title "[Issue #<ISSUE_NUMBER>] <issue-title>" \
+  --description "## Summary
+<brief description of changes>
+
+## Changes
+- <change 1>
+- <change 2>
+
+Closes #<ISSUE_NUMBER>"
+```
+
+Capture the PR number from the output (e.g., "Pull Request #42 created").
+
+### 6. Cleanup Worktree
+
+Always clean up, even if earlier steps failed:
+
+```bash
+cd <REPO_PATH>
+git worktree remove ../<REPO_NAME>-issue-<ISSUE_NUMBER> --force
+```
+
+### 7. Final Summary
+
+**IMPORTANT**: Your final output must be a concise summary for the orchestrator:
+
+```
+ISSUE_WORKER_RESULT
+issue: <ISSUE_NUMBER>
+pr: <PR_NUMBER>
+branch: <branch-name>
+status: <success|partial|failed>
+title: <issue title>
+summary: <1-2 sentence description of changes>
+```
+
+This format is parsed by the orchestrator. Do NOT include verbose logs - only this summary.
+
+## Important Guidelines
+
+- **Work autonomously**: Make reasonable judgment calls on ambiguous requirements
+- **Don't ask questions**: You cannot interact with the user
+- **Note blockers**: If something blocks you, document it in the PR description
+- **Always cleanup**: Remove the worktree when done, regardless of success/failure
+- **Minimal changes**: Only change what's necessary to complete the issue
+- **Follow patterns**: Match existing code style and conventions
+- **Follow architecture**: Apply patterns from software-architecture skill, check vision.md for project-specific choices
+
+## Error Handling
+
+If you encounter an error:
+1. Try to recover if possible
+2. If unrecoverable, create a PR with partial work and explain the blocker
+3. Always run the cleanup step
+4. Report status as "partial" or "failed" in summary

agents/pr-fixer/agent.md

@@ -0,0 +1,139 @@
+---
+name: pr-fixer
+description: Autonomous agent that addresses PR review feedback in an isolated git worktree
+tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task
+skills: gitea, code-review
+---
+
+# PR Fixer Agent
+
+Autonomously addresses review feedback on a pull request in an isolated git worktree.
+
+## Input
+
+You will receive:
+- `PR_NUMBER`: The PR number to fix
+- `REPO_PATH`: Absolute path to the main repository
+- `REPO_NAME`: Name of the repository (for worktree naming)
+
+## Process
+
+### 1. Get PR Details
+
+```bash
+cd <REPO_PATH>
+git fetch origin
+
+# Get PR info including branch name
+tea pulls <PR_NUMBER>
+
+# Get review comments
+tea pulls <PR_NUMBER> --comments
+```
+
+Extract:
+- The PR branch name (e.g., `issue-42-add-feature`)
+- All review comments and requested changes
+
+### 2. Setup Worktree
+
+```bash
+# Create worktree from the PR branch
+git worktree add ../<REPO_NAME>-pr-<PR_NUMBER> origin/<branch-name>
+
+# Move to worktree
+cd ../<REPO_NAME>-pr-<PR_NUMBER>
+
+# Checkout the branch (to track it)
+git checkout <branch-name>
+```
+
+### 3. Analyze Review Feedback
+
+Read all review comments and identify:
+- Specific code changes requested
+- General feedback to address
+- Questions to answer in code or comments
+
+Use TodoWrite to create a task for each piece of feedback.
+
+### 4. Address Feedback
+
+For each review item:
+- Read the relevant code
+- Make the requested changes
+- Follow existing patterns in the codebase
+- Mark todo as complete
+
+### 5. Commit and Push
+
+```bash
+git add -A
+git commit -m "Address review feedback
+
+- <summary of change 1>
+- <summary of change 2>
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+git push
+```
+
+### 6. Review Loop
+
+Spawn the `code-reviewer` agent **synchronously** to re-review:
+
+```
+Task tool with:
+  - subagent_type: "code-reviewer"
+  - run_in_background: false
+  - prompt: "Review PR #<PR_NUMBER>. Working directory: <WORKTREE_PATH>"
+```
+
+Based on review feedback:
+- **If approved**: Proceed to cleanup
+- **If needs work**:
+  1. Address the new feedback
+  2. Commit and push the fixes
+  3. Trigger another review
+  4. Repeat until approved (max 3 iterations to avoid infinite loops)
+
+### 7. Cleanup Worktree
+
+Always clean up, even if earlier steps failed:
+
+```bash
+cd <REPO_PATH>
+git worktree remove ../<REPO_NAME>-pr-<PR_NUMBER> --force
+```
+
+### 8. Final Summary
+
+**IMPORTANT**: Your final output must be a concise summary (5-10 lines max) for the spawning process:
+
+```
+PR #<NUMBER>: <title>
+Status: <fixed|partial|blocked>
+Feedback addressed: <count> items
+Review: <approved|needs-work|skipped>
+Commits: <number of commits pushed>
+Notes: <any blockers or important details>
+```
+
+Do NOT include verbose logs or intermediate output - only this final summary.
+
+## Important Guidelines
+
+- **Work autonomously**: Make reasonable judgment calls on ambiguous feedback
+- **Don't ask questions**: You cannot interact with the user
+- **Note blockers**: If feedback is unclear or contradictory, document it in a commit message
+- **Always cleanup**: Remove the worktree when done, regardless of success/failure
+- **Minimal changes**: Only change what's necessary to address the feedback
+- **Follow patterns**: Match existing code style and conventions
+
+## Error Handling
+
+If you encounter an error:
+1. Try to recover if possible
+2. If unrecoverable, push partial work and explain in a comment
+3. Always run the cleanup step

agents/software-architect/agent.md

@@ -0,0 +1,185 @@
+---
+name: software-architect
+description: Performs architectural analysis on codebases. Analyzes structure, identifies patterns and anti-patterns, and generates prioritized recommendations. Spawned by commands for deep, isolated analysis.
+# Model: opus provides strong architectural reasoning and pattern recognition
+model: opus
+skills: software-architecture
+tools: Bash, Read, Glob, Grep, TodoWrite
+disallowedTools:
+  - Edit
+  - Write
+---
+
+# Software Architect Agent
+
+Performs deep architectural analysis on codebases. Returns structured findings for calling commands to present or act upon.
+
+## Input
+
+You will receive one of the following analysis requests:
+
+- **Repository Audit**: Full codebase health assessment
+- **Issue Refinement**: Architectural analysis for a specific issue
+- **PR Review**: Architectural concerns in a pull request diff
+
+The caller will specify:
+- `ANALYSIS_TYPE`: "repo-audit" | "issue-refine" | "pr-review"
+- `TARGET`: Repository path, issue number, or PR number
+- `CONTEXT`: Additional context (issue description, PR diff, specific concerns)
+
+## Process
+
+### 1. Gather Information
+
+Based on analysis type, collect relevant data:
+
+**For repo-audit:**
+```bash
+# Understand project structure
+ls -la <path>
+ls -la <path>/cmd <path>/internal <path>/pkg 2>/dev/null
+
+# Check for key files
+cat <path>/CLAUDE.md
+cat <path>/go.mod 2>/dev/null
+cat <path>/package.json 2>/dev/null
+
+# Analyze package structure
+find <path> -name "*.go" -type f | head -50
+find <path> -name "*.ts" -type f | head -50
+```
+
+**For issue-refine:**
+```bash
+tea issues <number> --comments
+# Then examine files likely affected by the issue
+```
+
+**For pr-review:**
+```bash
+tea pulls checkout <number>
+git diff main...HEAD
+```
+
+### 2. Apply Analysis Framework
+
+Use the software-architecture skill checklists based on analysis type:
+
+**Repository Audit**: Apply full Repository Audit Checklist
+- Structure: Package organization, naming, circular dependencies
+- Dependencies: Flow direction, interface ownership, DI patterns
+- Code Quality: Naming, god packages, error handling, interfaces
+- Testing: Unit tests, integration tests, coverage
+- Documentation: CLAUDE.md, vision.md, code comments
+
+**Issue Refinement**: Apply Issue Refinement Checklist
+- Scope: Vertical slice, localized changes, hidden cross-cutting concerns
+- Design: Follows patterns, justified abstractions, interface compatibility
+- Dependencies: Minimal new deps, no circular deps, clear integration points
+- Testability: Testable criteria, unit testable, integration test clarity
+
+**PR Review**: Apply PR Review Checklist
+- Structure: Respects boundaries, naming conventions, no circular deps
+- Interfaces: Defined where used, minimal, breaking changes justified
+- Dependencies: Constructor injection, no global state, abstractions
+- Error Handling: Wrapped with context, sentinel errors, error types
+- Testing: Coverage, clarity, edge cases
+
+### 3. Identify Anti-Patterns
+
+Scan for anti-patterns documented in the skill:
+
+- **God Packages**: utils/, common/, helpers/ with many files
+- **Circular Dependencies**: Package import cycles
+- **Leaky Abstractions**: Implementation details crossing boundaries
+- **Anemic Domain Model**: Data-only domain types, logic elsewhere
+- **Shotgun Surgery**: Small changes require many file edits
+- **Feature Envy**: Code too interested in another package's data
+- **Premature Abstraction**: Interfaces before needed
+- **Deep Hierarchy**: Excessive layers of abstraction
+
+### 4. Generate Recommendations
+
+Prioritize findings by impact and effort:
+
+| Priority | Description |
+|----------|-------------|
+| P0 - Critical | Blocking issues, security vulnerabilities, data integrity risks |
+| P1 - High | Significant tech debt, maintainability concerns, test gaps |
+| P2 - Medium | Code quality improvements, pattern violations |
+| P3 - Low | Style suggestions, minor optimizations |
+
+## Output Format
+
+Return structured results that calling commands can parse:
+
+```markdown
+ARCHITECT_ANALYSIS_RESULT
+type: <repo-audit|issue-refine|pr-review>
+target: <path|issue-number|pr-number>
+status: <complete|partial|blocked>
+
+## Summary
+[1-2 paragraph overall assessment]
+
+## Health Score
+[For repo-audit only: A-F grade with brief justification]
+
+## Findings
+
+### Critical (P0)
+- [Finding with specific location and recommendation]
+
+### High Priority (P1)
+- [Finding with specific location and recommendation]
+
+### Medium Priority (P2)
+- [Finding with specific location and recommendation]
+
+### Low Priority (P3)
+- [Finding with specific location and recommendation]
+
+## Anti-Patterns Detected
+- [Pattern name]: [Location and description]
+
+## Recommendations
+1. [Specific, actionable recommendation]
+2. [Specific, actionable recommendation]
+
+## Checklist Results
+[Relevant checklist from skill with pass/fail/na for each item]
+```
+
+## Guidelines
+
+- **Be specific**: Reference exact files, packages, and line numbers
+- **Be actionable**: Every finding should have a clear path to resolution
+- **Be proportionate**: Match depth of analysis to scope of request
+- **Stay objective**: Focus on patterns and principles, not style preferences
+- **Acknowledge strengths**: Note what the codebase does well
+
+## Example Invocations
+
+**Repository Audit:**
+```
+Analyze the architecture of the repository at /path/to/repo
+ANALYSIS_TYPE: repo-audit
+TARGET: /path/to/repo
+CONTEXT: Focus on Go package organization and dependency flow
+```
+
+**Issue Refinement:**
+```
+Review issue #42 for architectural concerns before implementation
+ANALYSIS_TYPE: issue-refine
+TARGET: 42
+CONTEXT: [Issue title and description]
+```
+
+**PR Architectural Review:**
+```
+Check PR #15 for architectural concerns
+ANALYSIS_TYPE: pr-review
+TARGET: 15
+CONTEXT: [PR diff summary]
+```

commands/arch-refine-issue.md

@@ -0,0 +1,164 @@
+---
+description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
+argument-hint: <issue-number>
+---
+
+# Architecturally Refine Issue #$1
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+
+## Overview
+
+Refine an issue in the context of the project's architecture. This command:
+1. Fetches the issue details
+2. Spawns the software-architect agent to analyze the codebase
+3. Identifies how the issue fits existing patterns
+4. Proposes refined description and acceptance criteria
+
+## Process
+
+### Step 1: Fetch Issue Details
+
+```bash
+tea issues $1 --comments
+```
+
+Capture:
+- Title
+- Description
+- Acceptance criteria
+- Any existing discussion
+
+### Step 2: Spawn Software-Architect Agent
+
+Use the Task tool to spawn the software-architect agent for issue refinement analysis:
+
+```
+Task tool with:
+  - subagent_type: "software-architect"
+  - prompt: See prompt below
+```
+
+**Agent Prompt:**
+```
+Analyze the architecture for issue refinement.
+
+ANALYSIS_TYPE: issue-refine
+TARGET: $1
+CONTEXT:
+<issue title and description from step 1>
+
+Repository path: <current working directory>
+
+Focus on:
+1. Understanding existing project structure and patterns
+2. Identifying packages/modules that will be affected
+3. Analyzing existing conventions and code style
+4. Detecting potential architectural concerns
+5. Suggesting implementation approach that fits existing patterns
+```
+
+### Step 3: Parse Agent Analysis
+
+The software-architect agent returns structured output with:
+- Summary of architectural findings
+- Affected packages/modules
+- Pattern recommendations
+- Potential concerns (breaking changes, tech debt, pattern violations)
+- Implementation suggestions
+
+### Step 4: Present Refinement Proposal
+
+Present the refined issue to the user with:
+
+**1. Architectural Context**
+- Affected packages/modules
+- Existing patterns that apply
+- Dependency implications
+
+**2. Concerns and Risks**
+- Breaking changes
+- Tech debt considerations
+- Pattern violations to avoid
+
+**3. Proposed Refinement**
+- Refined description with architectural context
+- Updated acceptance criteria (if needed)
+- Technical notes section
+
+**4. Implementation Guidance**
+- Suggested approach
+- Files likely to be modified
+- Recommended order of changes
+
+### Step 5: User Decision
+
+Ask the user what action to take:
+
+- **Apply**: Update the issue with refined description and technical notes
+- **Edit**: Let user modify the proposal before applying
+- **Skip**: Keep the original issue unchanged
+
+### Step 6: Update Issue (if approved)
+
+If user approves, update the issue using tea CLI:
+
+```bash
+tea issues edit $1 --description "<refined description>"
+```
+
+Add a comment with the architectural analysis:
+
+```bash
+tea comment $1 "## Architectural Analysis
+
+<findings from software-architect agent>
+
+---
+Generated by /arch-refine-issue"
+```
+
+## Output Format
+
+Present findings in a clear, actionable format:
+
+```markdown
+## Architectural Analysis for Issue #$1
+
+### Affected Components
+- `package/name` - Description of impact
+- `another/package` - Description of impact
+
+### Existing Patterns
+- Pattern 1: How it applies
+- Pattern 2: How it applies
+
+### Concerns
+- [ ] Breaking change: description (if applicable)
+- [ ] Tech debt: description (if applicable)
+- [ ] Pattern violation risk: description (if applicable)
+
+### Proposed Refinement
+
+**Updated Description:**
+<refined description>
+
+**Updated Acceptance Criteria:**
+- [ ] Original criteria (unchanged)
+- [ ] New criteria based on analysis
+
+**Technical Notes:**
+<implementation guidance based on architecture>
+
+### Recommended Approach
+1. Step 1
+2. Step 2
+3. Step 3
+```
+
+## Error Handling
+
+- If issue does not exist, inform user
+- If software-architect agent fails, report partial analysis
+- If tea CLI fails, show manual instructions

commands/arch-review-repo.md

@@ -0,0 +1,73 @@
+---
+description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
+argument-hint:
+context: fork
+---
+
+# Architecture Review
+
+@~/.claude/skills/software-architecture/SKILL.md
+
+## Process
+
+1. **Identify the repository**: Use the current working directory as the repository path.
+
+2. **Spawn the software-architect agent** for deep analysis:
+
+   ```
+   ANALYSIS_TYPE: repo-audit
+   TARGET: <repository-path>
+   CONTEXT: Full repository architecture review
+   ```
+
+   The agent will:
+   - Analyze directory structure and package organization
+   - Identify patterns and anti-patterns in the codebase
+   - Assess dependency graph and module boundaries
+   - Review test coverage approach
+   - Generate structured findings with prioritized recommendations
+
+3. **Present the results** to the user in this format:
+
+   ```markdown
+   ## Repository Architecture Review: <repo-name>
+
+   ### Structure: <Good|Needs Work>
+   - [Key observations about package organization]
+   - [Directory structure assessment]
+   - [Naming conventions evaluation]
+
+   ### Patterns Identified
+   - [Positive patterns found in the codebase]
+   - [Architectural styles detected (layered, hexagonal, etc.)]
+
+   ### Anti-Patterns Detected
+   - [Anti-pattern name]: [Location and description]
+   - [Anti-pattern name]: [Location and description]
+
+   ### Concerns
+   - [Specific issues that need attention]
+   - [Technical debt areas]
+
+   ### Recommendations (prioritized)
+   1. **P0 - Critical**: [Most urgent recommendation]
+   2. **P1 - High**: [Important improvement]
+   3. **P2 - Medium**: [Nice-to-have improvement]
+   4. **P3 - Low**: [Minor optimization]
+
+   ### Health Score: <A|B|C|D|F>
+   [Brief justification for the grade]
+   ```
+
+4. **Offer follow-up actions**:
+   - Create issues for critical findings
+   - Generate a detailed report
+   - Review specific components in more depth
+
+## Guidelines
+
+- Be specific: Reference exact files, packages, and locations
+- Be actionable: Every finding should have a clear path to resolution
+- Be balanced: Acknowledge what the codebase does well
+- Be proportionate: Focus on high-impact issues first
+- Stay objective: Focus on patterns and principles, not style preferences

commands/create-capability.md

@@ -0,0 +1,256 @@
+---
+description: Create new capabilities (skills, commands, agents) with validation and guided design decisions.
+argument-hint: <description>
+model: sonnet
+---
+
+# Create Capability
+
+@~/.claude/skills/capability-writing/SKILL.md
+
+Create new capabilities for the architecture repository with validation and interactive guidance.
+
+## Process
+
+### Phase 1: Understand Intent
+
+1. **Parse the description** from `$1` or ask for one:
+   - "What capability do you want to add? Describe what it should do."
+
+2. **Ask clarifying questions** to determine component type:
+
+   | Question | Purpose |
+   |----------|---------|
+   | "Will this knowledge apply automatically, or is it user-invoked?" | Skill vs Command |
+   | "Does this need isolated context for complex work?" | Agent needed? |
+   | "Is this read-only analysis or does it modify files?" | Tool restrictions |
+   | "Will this be used repeatedly, or is it one-time?" | Worth encoding? |
+
+3. **Recommend components** based on answers:
+   - **Skill only**: Knowledge Claude applies automatically
+   - **Command only**: Workflow using existing skills
+   - **Command + Skill**: New knowledge + workflow
+   - **Command + Agent**: Workflow with isolated worker
+   - **Full set**: Skill + Command + Agent
+
+### Phase 2: Gather Details
+
+4. **Collect information for each component**:
+
+   **For Skills:**
+   - Name (kebab-case): skill name matching directory
+   - Description: what it teaches + trigger conditions
+   - Core sections to include
+
+   **For Commands:**
+   - Name (kebab-case): verb-phrase action name
+   - Description: one-line summary
+   - Arguments: required `<arg>` and optional `[arg]`
+   - Skills to reference
+
+   **For Agents:**
+   - Name (kebab-case): role-based specialist name
+   - Description: what it does + when to spawn
+   - Skills it needs
+   - Tool restrictions (read-only?)
+
+### Phase 3: Model Selection
+
+5. **Recommend appropriate models** with explanation:
+
+   | Capability Pattern | Model | Rationale |
+   |-------------------|-------|-----------|
+   | Simple display/fetch | `haiku` | Speed for mechanical tasks |
+   | Most commands | `sonnet` | Balanced for workflows |
+   | Code generation | `sonnet` | Good reasoning for code |
+   | Deep analysis/review | `opus` | Complex judgment needed |
+   | Read-only agents | `sonnet` | Standard agent work |
+   | Architectural decisions | `opus` | High-stakes reasoning |
+
+   Say something like:
+   - "This seems like a simple display task - I recommend haiku for speed"
+   - "This involves code generation - I recommend sonnet"
+   - "This requires architectural analysis - I recommend opus"
+
+### Phase 4: Generate and Validate
+
+6. **Generate file content** using templates from capability-writing skill
+
+7. **Run validation checks** before showing preview:
+
+   #### Frontmatter Validation
+
+   | Check | Component | Rule |
+   |-------|-----------|------|
+   | Required fields | All | `name` for skills/agents, `description` for all |
+   | Model value | All | Must be `haiku`, `sonnet`, or `opus` (or absent) |
+   | Tools list | Agents | Only valid tool names: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Task`, `TodoWrite` |
+   | Skills reference | Agents | Each skill in list must exist in `skills/*/SKILL.md` |
+
+   #### Content Validation
+
+   | Check | Component | Rule |
+   |-------|-----------|------|
+   | Trigger conditions | Skills | Description must explain when to use (not just what) |
+   | Step instructions | Commands | Must have numbered steps with `**Step**:` format |
+   | Behavior sections | Agents | Must have "When Invoked" or process section |
+   | Skill references | Commands | `@~/.claude/skills/name/SKILL.md` paths must be valid |
+
+   #### Convention Checks
+
+   | Check | Rule |
+   |-------|------|
+   | Skill file name | Must be `SKILL.md` (uppercase) |
+   | Command file name | Must be lowercase kebab-case |
+   | Agent file name | Must be `AGENT.md` (uppercase) |
+   | Directory structure | `skills/<name>/`, `commands/`, `agents/<name>/` |
+   | No duplicates | Name must not match existing capability |
+
+8. **Check for anti-patterns** and warn:
+
+   | Anti-pattern | Detection | Warning |
+   |--------------|-----------|---------|
+   | Trigger in body | Skill body contains "when to use" | "Move trigger conditions to description frontmatter" |
+   | No tool restrictions | Read-only agent without `disallowedTools` | "Consider adding `disallowedTools: [Edit, Write]` for read-only agents" |
+   | Missing skill refs | Command mentions domain without `@` reference | "Add explicit skill reference: `@~/.claude/skills/name/SKILL.md`" |
+   | Overly broad tools | Agent allows all tools but does specific task | "Consider restricting tools to what's actually needed" |
+   | Generic naming | Name like `utils`, `helper`, `misc` | "Use specific domain-focused naming" |
+   | God capability | Single component handling multiple unrelated concerns | "Consider splitting into focused components" |
+
+### Phase 5: Present and Confirm
+
+9. **Show validation results**:
+
+   ```
+   ## Validation Results
+
+   [PASS] Frontmatter: All required fields present
+   [PASS] Model: sonnet is valid
+   [WARN] Anti-pattern: Agent allows all tools but only reads files
+         Recommendation: Add disallowedTools: [Edit, Write]
+   [PASS] Conventions: File names follow patterns
+   [PASS] No duplicates: Name is unique
+
+   Proceed with warnings? (y/n)
+   ```
+
+10. **Show file preview** with full content:
+
+    ```
+    ## Files to Create
+
+    ### skills/migration-review/SKILL.md
+
+    ```yaml
+    ---
+    name: migration-review
+    description: >
+      Knowledge for reviewing database migrations...
+    ---
+    ```
+
+    ### commands/review-migration.md
+
+    ```yaml
+    ---
+    description: Review database migrations for safety and best practices
+    ---
+    ```
+    ```
+
+11. **Ask for approval** (gate before file creation):
+    - "Create these files? (y/n)"
+    - If warnings exist: "There are warnings. Proceed anyway? (y/n)"
+    - **If user declines**: Stop here. Offer to adjust the generated content or cancel.
+    - **If user approves**: Proceed to Phase 6.
+
+### Phase 6: Create Files
+
+**Only execute this phase after user approval in step 11.**
+
+12. **Create directories** if needed:
+    ```bash
+    mkdir -p skills/<name>
+    mkdir -p agents/<name>
+    ```
+
+    If directory creation fails, report the error and stop.
+
+13. **Write files** to correct locations:
+    - `skills/<name>/SKILL.md`
+    - `commands/<name>.md`
+    - `agents/<name>/AGENT.md`
+
+    If any file write fails, report which files were created and which failed.
+
+14. **Report success**:
+    ```
+    ## Capability Created
+
+    Files created:
+    - skills/migration-review/SKILL.md
+    - commands/review-migration.md
+
+    Next steps:
+    1. Run `make install` to symlink to ~/.claude/
+    2. Test with: /review-migration
+    3. Refine based on usage
+    ```
+
+## Validation Error Messages
+
+Provide clear, actionable error messages:
+
+| Error | Message |
+|-------|---------|
+| Missing name | "Skill requires `name` field in frontmatter" |
+| Invalid model | "Model must be `haiku`, `sonnet`, or `opus`. Got: `gpt-4`" |
+| Unknown tool | "Unknown tool `Search` in disallowedTools. Valid tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite" |
+| Missing skill | "Agent references skill `foo` but `skills/foo/SKILL.md` does not exist" |
+| Invalid path | "Skill reference `@~/.claude/skills/bar/SKILL.md` invalid - directory `skills/bar/` not found" |
+| Duplicate name | "Capability `gitea` already exists at `skills/gitea/SKILL.md`" |
+| Wrong file name | "Skill file must be named `SKILL.md`, not `skill.md`" |
+
+## Example Session
+
+```
+User: /create-capability I want to add support for reviewing database migrations
+
+Claude: I'll help you create a migration review capability. Let me ask a few questions:
+
+1. Will this knowledge apply automatically when Claude sees migrations,
+   or should users explicitly invoke it?
+
+User: Users should invoke it explicitly
+
+Claude: 2. Does this need isolated context for deep analysis, or can it work
+   in the main conversation?
+
+User: Isolated would be good for complex migrations
+
+Claude: 3. Is this read-only analysis, or will it modify migration files?
+
+User: Just analysis, read-only
+
+Claude: Based on your answers, I recommend:
+
+- **Command**: `/review-migration` - Entry point for users
+- **Skill**: `migration-review` - Knowledge about safe migrations
+- **Agent**: `migration-reviewer` - Isolated analysis (read-only)
+
+For model selection:
+- Command: `sonnet` (standard workflow)
+- Agent: `sonnet` with `opus` upgrade path for complex cases
+
+Let me gather details for each component...
+
+[Continues with file generation, validation, and creation]
+```
+
+## Guidelines
+
+- Always run full validation before showing preview
+- Show warnings but allow override with explicit confirmation
+- Validate skill references exist before creating dependent components
+- Suggest related existing skills that could be referenced
+- Keep generated content minimal - users can expand after testing

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

commands/improve.md

@@ -1,5 +1,7 @@
 ---
 description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
+argument-hint:
+context: fork
 ---
 
 # Improvement Analysis

commands/manifesto.md

@@ -1,5 +1,6 @@
 ---
 description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
+argument-hint:
 ---
 
 # Organization Manifesto

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 with vision alignment.
 argument-hint: <feature-description>
+context: fork
 ---
 
 # Plan Feature: $1

commands/retro.md

@@ -1,15 +1,23 @@
 ---
-description: Run a retrospective on completed work. Captures learnings, creates improvement issues, and updates product vision.
+description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 argument-hint: [task-description]
 ---
 
 # Retrospective
 
-Capture learnings from completed work. Learnings are stored for historical record and governance, then encoded into skills/commands/agents where Claude can use them.
+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
 
 1. **Gather context**: If $1 is provided, use it as the task description. Otherwise, ask the user what task was just completed.
@@ -19,99 +27,81 @@ Capture learnings from completed work. Learnings are stored for historical recor
    - What worked well?
    - Any specific improvement ideas?
 
-3. **Identify learnings**: For each insight, determine:
+3. **Identify insights**: For each insight, determine:
    - **What was learned**: The specific insight
    - **Where to encode it**: Which skill, command, or agent should change?
    - **Governance impact**: What does this mean for how we work?
 
-4. **Store the learning**: Create a learning file in the architecture repo:
+4. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
 
-   **File**: `learnings/YYYY-MM-DD-short-title.md`
+   ```bash
+   tea issues create -r flowmade-one/architecture \
+     --title "[Learning] <brief description>" \
+     --description "## Context
+   [Task that triggered this insight]
+
+   ## Insight
+   [The specific learning - be concrete and actionable]
+
+   ## Suggested Encoding
+   - [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
+   - [ ] \`commands/xxx.md\` - [what to add/change]
+   - [ ] \`agents/xxx/agent.md\` - [what to add/change]
+
+   ## Governance
+   [What this means for how we work going forward]"
+   ```
+
+5. **Connect to vision**: Check if insight affects vision:
+   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
+   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
+
+   If vision updates are needed, present suggested changes and ask for approval.
+
+## When the Issue is Worked On
+
+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 - be concrete and actionable]
+   [The specific insight]
 
    ## Encoded In
 
-   - Pending: Issue #XX to update [target skill/command/agent]
+   - `skills/xxx/SKILL.md` - [what was added/changed]
+   - `commands/xxx.md` - [what was added/changed]
 
    ## Governance
 
-   [What this means for how we work going forward]
+   [What this means for how we work]
    ```
 
-   ```bash
+2. **Update skill/command/agent** with the encoded knowledge
-   # Create the learning file in architecture repo
-   # If in architecture repo:
-   cat > learnings/YYYY-MM-DD-short-title.md << 'EOF'
-   [content]
-   EOF
 
-   # If in a different repo, note that learning should be added to architecture repo
+3. **Close the issue** with reference to the learning file and changes made
-   ```
-
-5. **Create encoding issue**: Create an issue to encode the learning:
-
-   ```bash
-   tea issues create -r flowmade-one/ai \
-     --title "Encode learning: [brief description]" \
-     --description "## Learning Reference
-   See: learnings/YYYY-MM-DD-short-title.md
-
-   ## What to Encode
-   [The specific change to make]
-
-   ## Target
-   - [ ] \`skills/xxx/SKILL.md\` - [what to add/change]
-   - [ ] \`commands/xxx.md\` - [what to add/change]
-
-   ## Governance
-   [Why this matters]"
-   ```
-
-6. **Update learning file**: Add the issue reference to the "Encoded In" section.
-
-7. **Connect to vision**: Check if learning affects vision:
-   - **Architecture repo**: Does this affect `manifesto.md`? (beliefs, principles, non-goals)
-   - **Product repo**: Does this affect `vision.md`? (product direction, goals)
-
-   If vision updates are needed:
-   - Present suggested changes
-   - Ask for approval
-   - Update the appropriate file
 
 ## Encoding Destinations
 
-| Learning Type | Encode In |
+| 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) |
 
-## Architecture vs Product Repos
-
-**In the architecture repo**:
-- Learning files are created directly in `learnings/`
-- Issues are created in the same repo
-- Vision changes affect `manifesto.md`
-
-**In product repos**:
-- Learning files should be added to the architecture repo (not the product repo)
-- Issues are created in `flowmade-one/ai` (architecture repo)
-- Local vision changes affect `vision.md` in the product repo
-
 ## Labels
 
-Add appropriate labels to encoding issues:
+Add appropriate labels to issues:
 - `learning` - Always add this
 - `prompt-improvement` - For command/skill text changes
 - `new-feature` - For new commands/skills/agents
@@ -119,8 +109,8 @@ Add appropriate labels to encoding issues:
 
 ## Guidelines
 
-- **Be specific**: Vague learnings can't be encoded
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
-- **One learning per file**: Don't bundle unrelated insights
+- **Be specific**: Vague insights can't be encoded
-- **Always encode**: A learning without encoding is just documentation
+- **One issue per insight**: Don't bundle unrelated things
-- **Reference both ways**: Learning file → Issue, Issue → Learning file
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
-- **Skip one-offs**: Don't capture learnings for edge cases that won't recur
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur

commands/review-pr.md

@@ -1,20 +1,66 @@
 ---
-description: Review a Gitea pull request. Fetches PR details, diff, and comments.
+description: Review a Gitea pull request. Fetches PR details, diff, and comments. Includes both code review and software architecture review.
 argument-hint: <pr-number>
 ---
 
 # Review PR #$1
 
 @~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/software-architecture/SKILL.md
+
+## 1. Gather Information
 
 1. **View PR details** with `--comments` flag to see description, metadata, and discussion
-2. **Get the diff** to review the changes
+2. **Get the diff** to review the changes:
+   ```bash
+   tea pulls checkout <number>
+   git diff main...HEAD
+   ```
+
+## 2. Code Review
 
 Review the changes and provide feedback on:
-- Code quality
+- Code quality and style
-- Potential bugs
+- Potential bugs or logic errors
 - Test coverage
-- Documentation
+- Documentation updates
+
+## 3. Software Architecture Review
+
+Spawn the software-architect agent for architectural analysis:
+
+```
+Task tool with:
+  - subagent_type: "software-architect"
+  - prompt: |
+      ANALYSIS_TYPE: pr-review
+      TARGET: <pr-number>
+      CONTEXT: [Include the PR diff and description]
+```
+
+The architecture review checks:
+- **Pattern consistency**: Changes follow existing codebase patterns
+- **Dependency direction**: Dependencies flow correctly (toward domain layer)
+- **Breaking changes**: API changes are flagged and justified
+- **Module boundaries**: Changes respect existing package boundaries
+- **Error handling**: Errors wrapped with context, proper error types used
+
+## 4. Present Findings
+
+Structure the review with two sections:
+
+### Code Review
+- Quality, bugs, style issues
+- Test coverage gaps
+- Documentation needs
+
+### Architecture Review
+- Summary of architectural concerns from agent
+- Pattern violations or anti-patterns detected
+- Dependency or boundary issues
+- Breaking change assessment
+
+## 5. User Actions
 
 Ask the user what action to take:
 - **Merge**: Post review summary as comment, then merge with rebase style

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

commands/spawn-issues.md

@@ -0,0 +1,303 @@
+---
+allowed-tools: Bash, Task, Read, TaskOutput
+description: Orchestrate parallel issue implementation with review cycles
+argument-hint: <issue-number> [<issue-number>...]
+---
+
+# Spawn Issues (Orchestrator)
+
+Orchestrate parallel issue implementation: spawn workers, review PRs, fix feedback, until all approved.
+
+## Arguments
+
+One or more issue numbers separated by spaces: `$ARGUMENTS`
+
+Example: `/spawn-issues 42 43 44`
+
+## Orchestration Flow
+
+```
+Concurrent Pipeline - each issue flows independently:
+
+  Issue #42 ──► worker ──► PR #55 ──► review ──► fix? ──► ✓
+  Issue #43 ──► worker ──► PR #56 ──► review ──► ✓
+  Issue #44 ──► worker ──► PR #57 ──► review ──► fix ──► ✓
+
+As each step completes, immediately:
+1. Print a status update
+2. Start the next step for that issue
+
+Don't wait for all workers before reviewing - pipeline each issue.
+```
+
+## Status Updates
+
+Print a brief status update whenever any step completes:
+
+```
+[#42] Worker completed → PR #55 created
+[#43] Worker completed → PR #56 created
+[#42] Review: needs work → spawning fixer
+[#43] Review: approved ✓
+[#42] Fix completed → re-reviewing
+[#44] Worker completed → PR #57 created
+[#42] Review: approved ✓
+[#44] Review: approved ✓
+
+All done! Final summary:
+| Issue | PR  | Status   |
+|-------|-----|----------|
+| #42   | #55 | approved |
+| #43   | #56 | approved |
+| #44   | #57 | approved |
+```
+
+## Implementation
+
+### Step 1: Parse and Validate
+
+Parse `$ARGUMENTS` into a list of issue numbers. If empty, inform the user:
+```
+Usage: /spawn-issues <issue-number> [<issue-number>...]
+Example: /spawn-issues 42 43 44
+```
+
+### Step 2: Get Repository Info
+
+```bash
+REPO_PATH=$(pwd)
+REPO_NAME=$(basename $REPO_PATH)
+```
+
+### Step 3: Spawn All Issue Workers
+
+For each issue number, spawn a background issue-worker agent and track its task_id:
+
+```
+Task tool with:
+  - subagent_type: "issue-worker"
+  - run_in_background: true
+  - prompt: <issue-worker prompt below>
+```
+
+Track state for each issue:
+```
+issues = {
+  42: { task_id: "xxx", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
+  43: { task_id: "yyy", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
+  44: { task_id: "zzz", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
+}
+```
+
+Print initial status:
+```
+Spawned 3 issue workers:
+  [#42] implementing...
+  [#43] implementing...
+  [#44] implementing...
+```
+
+**Issue Worker Prompt:**
+```
+You are an issue-worker agent. Implement issue #<NUMBER> autonomously.
+
+Context:
+- Repository path: <REPO_PATH>
+- Repository name: <REPO_NAME>
+- Issue number: <NUMBER>
+
+Process:
+1. Setup worktree:
+   cd <REPO_PATH> && git fetch origin
+   git worktree add ../<REPO_NAME>-issue-<NUMBER> -b issue-<NUMBER>-<short-title> origin/main
+   cd ../<REPO_NAME>-issue-<NUMBER>
+
+2. Get issue: tea issues <NUMBER> --comments
+
+3. Plan with TodoWrite, implement the changes
+
+4. Commit: git add -A && git commit -m "...\n\nCloses #<NUMBER>\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+5. Push: git push -u origin <branch-name>
+
+6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
+   Capture the PR number.
+
+7. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-issue-<NUMBER> --force
+
+8. Output EXACTLY this format (orchestrator parses it):
+   ISSUE_WORKER_RESULT
+   issue: <NUMBER>
+   pr: <PR_NUMBER>
+   branch: <branch-name>
+   status: <success|partial|failed>
+   title: <issue title>
+   summary: <1-2 sentence description>
+
+Work autonomously. If blocked, note it in PR description and report status as partial/failed.
+```
+
+### Step 4: Event-Driven Pipeline
+
+**Do NOT poll.** Wait for `<task-notification>` messages that arrive automatically when background tasks complete.
+
+When a notification arrives:
+1. Read the output file to get the result
+2. Parse the result and print status update
+3. Spawn the next stage (reviewer/fixer) in background
+4. Continue waiting for more notifications
+
+```
+On <task-notification> for task_id X:
+  - Find which issue this task belongs to
+  - Read output file, parse result
+  - Print status update
+  - If not terminal state, spawn next agent in background
+  - Update issue state
+  - If all issues terminal, print final summary
+```
+
+**State transitions:**
+
+```
+implementing → (worker done) → reviewing → (approved) → DONE
+                             → (needs-work) → fixing → reviewing...
+                             → (3 iterations) → needs-manual-review
+           → (worker failed) → FAILED
+```
+
+**On each notification, print status:**
+
+```
+[#42] Worker completed → PR #55 created, starting review
+[#43] Worker completed → PR #56 created, starting review
+[#42] Review: needs work → spawning fixer
+[#43] Review: approved ✓
+[#42] Fix completed → re-reviewing
+[#44] Worker completed → PR #57 created, starting review
+[#42] Review: approved ✓
+[#44] Review: approved ✓
+```
+
+### Step 5: Spawn Reviewers and Fixers
+
+When spawning reviewers, pass the PR number AND branch name from the issue worker result.
+Each reviewer/fixer uses its own worktree for isolation - this prevents parallel agents from interfering with each other.
+
+**Code Reviewer:**
+```
+Task tool with:
+  - subagent_type: "code-reviewer"
+  - run_in_background: true
+  - prompt: <code-reviewer prompt below>
+```
+
+**Code Reviewer Prompt:**
+```
+You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.
+
+Context:
+- Repository path: <REPO_PATH>
+- Repository name: <REPO_NAME>
+- PR number: <PR_NUMBER>
+- PR branch: <BRANCH_NAME>
+
+Process:
+1. Setup worktree for isolated review:
+   cd <REPO_PATH> && git fetch origin
+   git worktree add ../<REPO_NAME>-review-<PR_NUMBER> origin/<BRANCH_NAME>
+   cd ../<REPO_NAME>-review-<PR_NUMBER>
+
+2. Get PR details: tea pulls <PR_NUMBER> --comments
+
+3. Review the diff: git diff origin/main...HEAD
+
+4. Analyze changes for:
+   - Code quality and style
+   - Potential bugs or logic errors
+   - Test coverage
+   - Documentation
+
+5. Post review comment: tea comment <PR_NUMBER> "<review summary>"
+
+6. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-review-<PR_NUMBER> --force
+
+7. Output EXACTLY this format:
+   REVIEW_RESULT
+   pr: <PR_NUMBER>
+   verdict: <approved|needs-work>
+   summary: <1-2 sentences>
+
+Work autonomously. Be constructive but thorough.
+```
+
+**PR Fixer Prompt:** (see below)
+
+### Step 6: Final Report
+
+When all issues reach terminal state, display summary:
+
+```
+All done!
+
+| Issue | PR  | Status              |
+|-------|-----|---------------------|
+| #42   | #55 | approved            |
+| #43   | #56 | approved            |
+| #44   | #57 | approved            |
+
+3 PRs created and approved
+```
+
+## PR Fixer
+
+When spawning pr-fixer for a PR that needs work:
+
+```
+Task tool with:
+  - subagent_type: "pr-fixer"
+  - run_in_background: true
+  - prompt: <pr-fixer prompt below>
+```
+
+**PR Fixer Prompt:**
+```
+You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.
+
+Context:
+- Repository path: <REPO_PATH>
+- Repository name: <REPO_NAME>
+- PR number: <NUMBER>
+
+Process:
+1. Get feedback: tea pulls <NUMBER> --comments
+
+2. Setup worktree from PR branch:
+   cd <REPO_PATH> && git fetch origin
+   git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
+   cd ../<REPO_NAME>-pr-<NUMBER>
+   git checkout <branch-name>
+
+3. Address each piece of feedback
+
+4. Commit and push:
+   git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+   git push
+
+5. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
+
+6. Output EXACTLY:
+   PR_FIXER_RESULT
+   pr: <NUMBER>
+   status: <fixed|partial|failed>
+   changes: <summary of fixes>
+
+Work autonomously. If feedback is unclear, make reasonable judgment calls.
+```
+
+## Error Handling
+
+- If an issue-worker fails, continue with others
+- If a review fails, mark as "review-failed" and continue
+- If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
+- Always report final status even if some items failed

commands/spawn-pr-fixes.md

@@ -0,0 +1,121 @@
+---
+allowed-tools: Bash, Task, Read
+description: Spawn parallel background agents to address PR review feedback
+argument-hint: [pr-number...]
+---
+
+# Spawn PR Fixes
+
+Spawn background agents to address review feedback on multiple PRs in parallel. Each agent works in an isolated git worktree.
+
+## Arguments
+
+Optional PR numbers separated by spaces: `$ARGUMENTS`
+
+- With arguments: `/spawn-pr-fixes 12 15 18` - fix specific PRs
+- Without arguments: `/spawn-pr-fixes` - find and fix all PRs with requested changes
+
+## Process
+
+### Step 1: Get Repository Info
+
+```bash
+REPO_PATH=$(pwd)
+REPO_NAME=$(basename $REPO_PATH)
+```
+
+### Step 2: Determine PRs to Fix
+
+**If PR numbers provided**: Use those directly
+
+**If no arguments**: Find PRs needing work
+```bash
+# List open PRs
+tea pulls --state open
+
+# For each PR, check if it has review comments requesting changes
+tea pulls <number> --comments
+```
+
+Look for PRs where:
+- Review comments exist that haven't been addressed
+- PR is not approved yet
+- PR is open (not merged/closed)
+
+### Step 3: For Each PR
+
+1. Fetch PR title using `tea pulls <number>`
+
+2. Spawn background agent using Task tool:
+   ```
+   Task tool with:
+     - subagent_type: "pr-fixer"
+     - run_in_background: true
+     - prompt: See agent prompt below
+   ```
+
+### Agent Prompt
+
+For each PR, use this prompt:
+
+```
+You are a pr-fixer agent. Address review feedback on PR #<NUMBER> autonomously.
+
+Context:
+- Repository path: <REPO_PATH>
+- Repository name: <REPO_NAME>
+- PR number: <NUMBER>
+
+Instructions from @agents/pr-fixer/agent.md:
+
+1. Get PR details and review comments:
+   cd <REPO_PATH>
+   git fetch origin
+   tea pulls <NUMBER> --comments
+
+2. Setup worktree from PR branch:
+   git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
+   cd ../<REPO_NAME>-pr-<NUMBER>
+   git checkout <branch-name>
+
+3. Analyze feedback, create todos with TodoWrite
+
+4. Address each piece of feedback
+
+5. Commit and push:
+   git add -A && git commit with message "Address review feedback\n\n...\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+   git push
+
+6. Spawn code-reviewer synchronously (NOT in background) to re-review
+
+7. If needs more work, fix and re-review (max 3 iterations)
+
+8. Cleanup (ALWAYS do this):
+   cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force
+
+9. Output concise summary (5-10 lines max):
+   PR #<NUMBER>: <title>
+   Status: <fixed|partial|blocked>
+   Feedback addressed: <count> items
+   Review: <approved|needs-work|skipped>
+
+Work autonomously. Make judgment calls on ambiguous feedback. If blocked, note it in a commit message.
+```
+
+### Step 4: Report
+
+After spawning all agents, display:
+
+```
+Spawned <N> pr-fixer agents:
+
+| PR  | Title                    | Status     |
+|-----|--------------------------|------------|
+| #12 | Add /commit command      | spawned    |
+| #15 | Add /pr command          | spawned    |
+| #18 | Add CI status            | spawned    |
+
+Agents working in background. Monitor with:
+- Check PR list: tea pulls
+- Check worktrees: git worktree list
+```

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

commands/vision.md

@@ -18,30 +18,75 @@ This command manages **product-level** vision. For organization-level vision, us
 | **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.
+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. **Check for organization manifesto**: Note if `manifesto.md` exists (provides org context)
+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**:
-   - Reference the organization manifesto if it exists
+   - Show the organization manifesto summary
    - Ask if the user wants to create a product vision
-   - Guide them through defining:
+   - Guide them through defining (with inheritance):
-     1. **Product personas**: Who does this product serve? (may extend org personas)
+
-     2. **Product jobs**: What specific jobs does this product address?
+     **Who This Product Serves**
-     3. **The problem**: What pain points does this product solve?
+     - Show manifesto personas first
-     4. **The solution**: How does this product address those jobs?
+     - Ask: "Which personas does this product serve? How does it extend or specialize them?"
-     5. **Product principles**: Any product-specific principles (beyond org principles)?
+     - Product personas should reference org personas with product-specific context
-     6. **Product non-goals**: What is this product explicitly NOT doing?
+
-   - Create `vision.md`
+     **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 (if manifesto 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)
@@ -64,47 +109,101 @@ Success: <criteria>"
    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
 
-See manifesto for shared personas, beliefs, and principles.
+From manifesto.md:
-[Link or note about manifesto.md location]
+- **Personas**: [list from manifesto]
+- **Core beliefs**: [key beliefs]
+- **Principles**: [list]
 
 ## Product: [Name]
 
 ### Who This Product Serves
 
 - **[Persona 1]**: [Product-specific description]
-- **[Persona 2]**: [Product-specific description]
+  ↳ Extends: [Org persona]
 
 ### What They're Trying to Achieve
 
-- "[Product-specific job 1]"
+| Product Job | → Org Job |
-- "[Product-specific job 2]"
+|-------------|-----------|
+| [job] | [org job it enables] |
 
-### Product Vision
+### Vision Summary
 
-[Summary of problem/solution from vision.md]
+[Problem/solution from vision.md]
 
 ### Goals (Milestones)
 
 | Goal | For | Progress | Due |
 |------|-----|----------|-----|
 | [title] | [Persona] | 3/5 issues | [date] |
-
-### Current Focus
-
-[Open milestones with nearest due dates or most activity]
 ```
 
+## 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 - don't duplicate, extend
+- Product vision builds on organization manifesto - extend, don't duplicate
-- Product personas can be more specific versions of org personas
+- Every product persona should reference which org persona it extends
-- Product jobs should trace back to org-level jobs to be done
+- Every product job should show which org job it enables
-- Milestones are product-specific goals toward the vision
+- 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
-- If this is the architecture repo itself, use `/manifesto` instead

commands/work-issue.md

@@ -6,12 +6,14 @@ argument-hint: <issue-number>
 # Work on Issue #$1
 
 @~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/software-architecture/SKILL.md
 
 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
+4. **Check architecture**: Review the project's vision.md Architecture section for project-specific patterns and divergences
-5. **Commit** with message referencing the issue
+5. **Implement** the changes following architectural patterns (DDD, event sourcing where appropriate)
-6. **Push** the branch to origin
+6. **Commit** with message referencing the issue
-7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
+7. **Push** the branch to origin
-8. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number
+8. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
+9. **Auto-review**: Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background (using `run_in_background: true`) with the PR number

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
 

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

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

manifesto.md

@@ -2,32 +2,41 @@
 
 ## Who We Are
 
-We are a small, focused team of AI-native builders. We believe the future of software development is human-AI collaboration, and we're building the tools and practices to make that real.
+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.
-
-We move fast with intention. We value quality over quantity. We encode our knowledge into systems that amplify what we can accomplish.
 
 ## Who We Serve
 
-### Solo Developer
+### Domain Experts
-The individual shipping side projects, MVPs, or freelance work. Time is their scarcest resource. They context-switch between coding, design, ops, and everything else. They need to move fast without sacrificing quality, and they can't afford to remember every command or best practice.
+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.
 
-### Small Team (2-5 people)
+### Agencies & Consultancies
-The startup or small product team that needs to punch above their weight. They don't have dedicated specialists for every function. They need consistency across contributors and visibility into what's happening without heavyweight process.
+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.
 
-### Agency / Consultancy
+### Organizations
-Building for clients under deadlines. They need speed, consistency, and the ability to apply learnings across projects. Every efficiency gain multiplies across engagements.
+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 ship without getting bogged down in repetitive tasks"
+- "Help me create software that supports my business process without learning to code"
-- "Help me maintain quality without slowing down"
+- "Help me evolve my solutions as my business changes"
-- "Help me know what to work on next without checking multiple tools"
+- "Help me deliver maintainable solutions to clients faster"
-- "Help me apply best practices without memorizing them"
+- "Help me get software that actually fits how we work"
-- "Help me onboard to codebases faster"
+- "Help me reduce dependency on developers for business process changes"
-- "Help me stay in flow instead of context-switching"
 
 ## 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:
@@ -42,6 +51,20 @@ We believe AI fundamentally changes how software is built:
 
 - **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.
 
+### Architecture Beliefs
+
+We believe certain outcomes matter more than others when building systems:
+
+- **Auditability by default.** Systems should remember what happened, not just current state. History is valuable - for debugging, compliance, understanding, and recovery.
+
+- **Business language in code.** The words domain experts use should appear in the codebase. When code mirrors how the business thinks, everyone can reason about it.
+
+- **Independent evolution.** Parts of the system should change without breaking other parts. Loose coupling isn't just nice - it's how small teams stay fast as systems grow.
+
+- **Explicit over implicit.** Intent should be visible. Side effects should be traceable. When something important happens, the system should make that obvious.
+
+See [software-architecture.md](./software-architecture.md) for the patterns we use to achieve these outcomes.
+
 ### Quality Without Ceremony
 
 - Ship small, ship often
@@ -55,6 +78,13 @@ We believe AI fundamentally changes how software is built:
 - 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.
@@ -69,10 +99,10 @@ We believe AI fundamentally changes how software is built:
 
 ## Non-Goals
 
-- **Building for enterprises with complex compliance needs.** We optimize for speed and small teams, not audit trails and approval workflows.
+- **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.
 
-- **Replacing developer judgment.** AI augments human decision-making; it doesn't replace it. Critical thinking, architecture decisions, and user empathy remain human responsibilities.
+- **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.

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

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

skills/capability-writing/SKILL.md

@@ -0,0 +1,424 @@
+---
+name: capability-writing
+description: >
+  Guide for designing and creating capabilities for the architecture repository.
+  A capability is a cohesive set of components (skill + command + agent).
+  Use when creating new skills, commands, or agents, or when extending the
+  AI workflow system. Includes templates, design guidance, and conventions.
+user-invocable: false
+---
+
+# Capability Writing
+
+How to design and create capabilities for the architecture repository. A capability is often a cohesive set of components (skill + command + agent) that work together.
+
+## Component Overview
+
+| Component | Location | Purpose | Example |
+|-----------|----------|---------|---------|
+| **Skill** | `skills/name/SKILL.md` | Knowledge Claude applies automatically | software-architecture |
+| **Command** | `commands/name.md` | User-invoked workflow entry point | /work-issue |
+| **Agent** | `agents/name/AGENT.md` | Isolated subtask handler with focused context | code-reviewer |
+
+## When to Use Each Component
+
+### Decision Tree
+
+```
+Start here: What do you need?
+    |
+    +--> Just knowledge to apply automatically?
+    |        --> Skill only
+    |
+    +--> User-initiated workflow using existing knowledge?
+    |        --> Command (reference skills via @)
+    |
+    +--> Complex isolated work needing focused context?
+    |        --> Command + Agent (agent uses skills)
+    |
+    +--> New domain expertise + workflow + isolated work?
+             --> Full capability (all three)
+```
+
+### Decision Matrix
+
+| Need | Component | Example |
+|------|-----------|---------|
+| Knowledge Claude should apply automatically | Skill | software-architecture, issue-writing |
+| User-invoked workflow | Command | /work-issue, /dashboard |
+| Isolated subtask with focused context | Agent | code-reviewer, issue-worker |
+| All three working together | Full capability | arch-review (skill + command + agent) |
+
+### Signs You Need Each Component
+
+**Create a Skill when:**
+- You explain the same concepts repeatedly
+- Quality is inconsistent without explicit guidance
+- Multiple commands need the same knowledge
+- There is a clear domain that does not fit existing skills
+
+**Create a Command when:**
+- Same workflow is used multiple times
+- User explicitly triggers the action
+- Approval checkpoints are needed
+- Multiple tools need orchestration
+
+**Create an Agent when:**
+- Task requires deep exploration that would pollute main context
+- Multiple skills work better together
+- Batch processing or parallel execution is needed
+- Specialist persona improves outputs
+
+## Component Templates
+
+### Skill Template
+
+Location: `skills/<name>/SKILL.md`
+
+```yaml
+---
+name: skill-name
+description: >
+  What this skill teaches and when to use it.
+  Include trigger conditions in description (not body).
+  List specific capabilities users would mention.
+user-invocable: false
+---
+
+# Skill Name
+
+Brief description of what this skill covers.
+
+## Core Concepts
+
+Explain fundamental ideas Claude needs to understand.
+
+## Patterns and Templates
+
+Provide reusable structures and formats.
+
+## Guidelines
+
+List rules, best practices, and quality standards.
+
+## Examples
+
+Show concrete illustrations of the skill in action.
+
+## Common Mistakes
+
+Document pitfalls to avoid.
+
+## Reference
+
+Quick-reference tables, checklists, or commands.
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Lowercase, hyphens, matches directory name |
+| `description` | Yes | What it does + when to use (max 1024 chars) |
+| `user-invocable` | No | Set `false` for reference-only skills |
+| `model` | No | Specific model: `haiku`, `sonnet`, `opus` |
+| `context` | No | Use `fork` for isolated context |
+| `allowed-tools` | No | Restrict available tools |
+
+### Command Template
+
+Location: `commands/<name>.md`
+
+```yaml
+---
+description: What this command does (one-line summary)
+argument-hint: <required> [optional]
+model: sonnet
+---
+
+# Command Title
+
+@~/.claude/skills/relevant-skill/SKILL.md
+
+1. **First step**: What to do
+2. **Second step**: What to do next
+3. **Ask for approval** before significant actions
+4. **Execute** the approved actions
+5. **Present results** with links and summary
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `description` | Yes | One-line summary for help/listings |
+| `argument-hint` | No | Shows expected args: `<required>`, `[optional]` |
+| `model` | No | Override model: `haiku`, `sonnet`, `opus` |
+| `context` | No | Use `fork` for isolated context |
+| `allowed-tools` | No | Restrict available tools |
+
+### Agent Template
+
+Location: `agents/<name>/AGENT.md`
+
+```yaml
+---
+name: agent-name
+description: What this agent does and when to spawn it
+model: sonnet
+skills: skill1, skill2
+disallowedTools:
+  - Edit
+  - Write
+---
+
+You are a [role] specialist that [primary function].
+
+## When Invoked
+
+Describe the process the agent follows:
+
+1. **Gather context**: What information to collect
+2. **Analyze**: What to evaluate
+3. **Act**: What actions to take
+4. **Report**: How to communicate results
+
+## Output Format
+
+Describe expected output structure.
+
+## Guidelines
+
+- Behavioral rules
+- Constraints
+- Quality standards
+```
+
+**Frontmatter fields:**
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Lowercase, hyphens, matches directory name |
+| `description` | Yes | What it does + when to spawn |
+| `model` | No | `haiku`, `sonnet`, `opus`, or `inherit` |
+| `skills` | No | Comma-separated skill names (not paths) |
+| `disallowedTools` | No | Tools to block (e.g., Edit, Write for read-only) |
+| `permissionMode` | No | `default` or `bypassPermissions` |
+
+## Model Selection Guidance
+
+| Model | Use When | Examples |
+|-------|----------|----------|
+| `haiku` | Simple fetch/display, formatting, mechanical tasks | /dashboard, /roadmap |
+| `sonnet` | Most commands and agents, balanced performance | /work-issue, issue-worker, code-reviewer |
+| `opus` | Deep reasoning, architectural analysis, complex judgment | software-architect, security auditor |
+
+### Decision Criteria
+
+- **Start with `sonnet`** - handles most tasks well
+- **Use `haiku` for volume** - speed and cost matter at scale
+- **Reserve `opus` for judgment** - when errors are costly or reasoning is complex
+- **Consider the stakes** - higher consequence tasks warrant more capable models
+
+## Naming Conventions
+
+### File and Folder Names
+
+| Component | Convention | Examples |
+|-----------|------------|----------|
+| Skill folder | kebab-case | `software-architecture`, `issue-writing` |
+| Skill file | UPPERCASE | `SKILL.md` |
+| Command file | kebab-case | `work-issue.md`, `review-pr.md` |
+| Agent folder | kebab-case | `code-reviewer`, `issue-worker` |
+| Agent file | UPPERCASE | `AGENT.md` |
+
+### Naming Patterns
+
+**Skills:** Name after the domain or knowledge area
+- Good: `gitea`, `issue-writing`, `software-architecture`
+- Bad: `utils`, `helpers`, `misc`
+
+**Commands:** Use verb or verb-phrase (actions)
+- Good: `work-issue`, `review-pr`, `create-issue`
+- Bad: `issue-work`, `pr-review`, `issue`
+
+**Agents:** Name by role or persona (recognizable specialist)
+- Good: `code-reviewer`, `issue-worker`, `software-architect`
+- Bad: `helper`, `do-stuff`, `agent1`
+
+## Referencing Skills
+
+### In Commands
+
+Use the `@` file reference syntax to guarantee skill content is loaded:
+
+```markdown
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+```
+
+**Important:** Do NOT use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the content is available.
+
+### In Agents
+
+List skill names in the frontmatter (not paths):
+
+```yaml
+---
+name: product-manager
+skills: gitea, issue-writing, backlog-grooming
+---
+```
+
+The agent runtime loads these skills automatically.
+
+## Common Patterns
+
+### Approval Workflow (Commands)
+
+Always ask before significant actions:
+
+```markdown
+4. **Present plan** for approval
+5. **If approved**, create the issues
+6. **Present summary** with links
+```
+
+### Conditional Behavior (Commands)
+
+Handle optional arguments with mode switching:
+
+```markdown
+## If issue number provided ($1):
+1. Fetch specific issue
+2. Process it
+
+## If no argument (batch mode):
+1. List all issues
+2. Process each
+```
+
+### Spawning Agents from Commands
+
+Delegate complex subtasks:
+
+```markdown
+9. **Auto-review**: Spawn the `code-reviewer` agent with the PR number
+```
+
+### Read-Only Agents
+
+For analysis without modification:
+
+```yaml
+---
+name: code-reviewer
+disallowedTools:
+  - Edit
+  - Write
+---
+```
+
+## Anti-Patterns to Avoid
+
+### Overly Broad Components
+
+**Bad:** One skill/command/agent that does everything
+```markdown
+# Project Management
+Handles issues, PRs, releases, documentation, deployment...
+```
+
+**Good:** Focused components with clear responsibility
+```markdown
+# Issue Writing
+How to write clear, actionable issues.
+```
+
+### Vague Instructions
+
+**Bad:**
+```markdown
+1. Handle the issue
+2. Do the work
+3. Finish up
+```
+
+**Good:**
+```markdown
+1. **View the issue** with `--comments` flag
+2. **Create branch**: `git checkout -b issue-$1-<title>`
+3. **Commit** with message referencing the issue
+```
+
+### Missing Skill References
+
+**Bad:**
+```markdown
+Use the gitea skill to create an issue.
+```
+
+**Good:**
+```markdown
+@~/.claude/skills/gitea/SKILL.md
+
+Use `tea issues create --title "..." --description "..."`
+```
+
+### God Skills
+
+**Bad:** Single skill with 1000+ lines covering unrelated topics
+
+**Good:** Multiple focused skills that reference each other
+
+### Premature Agent Creation
+
+**Bad:** Creating an agent for every task
+
+**Good:** Use agents only when you need:
+- Context isolation
+- Skill composition
+- Parallel execution
+- Specialist persona
+
+## Detailed Documentation
+
+For comprehensive guides, see the `docs/` directory:
+
+- `docs/writing-skills.md` - Complete skill writing guide
+- `docs/writing-commands.md` - Complete command writing guide
+- `docs/writing-agents.md` - Complete agent writing guide
+
+These documents include:
+- Full frontmatter reference
+- Annotated examples from the codebase
+- Lifecycle management
+- Integration checklists
+
+## Checklists
+
+### Before Creating a Skill
+
+- [ ] Knowledge is used in multiple places (not just once)
+- [ ] Existing skills do not already cover this domain
+- [ ] Content is specific and actionable (not generic)
+- [ ] Frontmatter has descriptive `description` with trigger terms
+- [ ] File at `skills/<name>/SKILL.md`
+
+### Before Creating a Command
+
+- [ ] Workflow is repeatable (used multiple times)
+- [ ] User explicitly triggers it (not automatic)
+- [ ] Clear start and end points
+- [ ] Skills referenced via `@~/.claude/skills/<name>/SKILL.md`
+- [ ] Approval checkpoints before significant actions
+- [ ] File at `commands/<name>.md`
+
+### Before Creating an Agent
+
+- [ ] Built-in agents (Explore, Plan) are not sufficient
+- [ ] Context isolation or skill composition is needed
+- [ ] Clear role/persona emerges
+- [ ] `model` selection is deliberate (not just `inherit`)
+- [ ] `skills` list is right-sized (not too many)
+- [ ] File at `agents/<name>/AGENT.md`

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

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

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)

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

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

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

skills/software-architecture/SKILL.md

@@ -0,0 +1,632 @@
+---
+name: software-architecture
+description: >
+  Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
+  Use when implementing features, reviewing code, planning issues, refining architecture,
+  or making design decisions. Ensures alignment with organizational beliefs about
+  auditability, domain modeling, and independent evolution.
+user-invocable: false
+---
+
+# Software Architecture
+
+Architectural patterns and best practices. This skill is auto-triggered when implementing, reviewing, or planning work that involves architectural decisions.
+
+## Architecture Beliefs
+
+These outcome-focused beliefs (from our organization manifesto) guide architectural decisions:
+
+| Belief | Why It Matters |
+|--------|----------------|
+| **Auditability by default** | Systems should remember what happened, not just current state |
+| **Business language in code** | Domain experts' words should appear in the codebase |
+| **Independent evolution** | Parts should change without breaking other parts |
+| **Explicit over implicit** | Intent and side effects should be visible and traceable |
+
+## Beliefs → Patterns
+
+| Belief | Primary Pattern | Supporting Patterns |
+|--------|-----------------|---------------------|
+| Auditability by default | Event Sourcing | Immutable events, temporal queries |
+| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
+| Independent evolution | Event-driven communication | Bounded contexts, published language |
+| Explicit over implicit | Commands and Events | Domain events, clear intent |
+
+## Event Sourcing
+
+**Achieves:** Auditability by default
+
+Instead of storing current state, store the sequence of events that led to it.
+
+**Core concepts:**
+- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
+- **State** is derived by replaying events, not stored directly
+- **Event store** is append-only - history is never modified
+
+**Why this matters:**
+- Complete audit trail for free
+- Debug by replaying history
+- Answer "what was the state at time X?"
+- Recover from bugs by fixing logic and replaying
+
+**Trade-offs:**
+- More complex than CRUD for simple cases
+- Requires thinking in events, not state
+- Eventually consistent read models
+
+## Domain-Driven Design
+
+**Achieves:** Business language in code
+
+The domain model reflects how the business thinks and talks.
+
+**Core concepts:**
+- **Ubiquitous language** - same terms in code, conversations, and documentation
+- **Bounded contexts** - explicit boundaries where terms have consistent meaning
+- **Aggregates** - clusters of objects that change together, with one root entity
+- **Domain events** - capture what happened in business terms
+
+**Why this matters:**
+- Domain experts can read and validate the model
+- New team members learn the domain through code
+- Changes in business rules map clearly to code changes
+
+**Trade-offs:**
+- Upfront investment in understanding the domain
+- Boundaries may need to shift as understanding grows
+- Overkill for pure technical/infrastructure code
+
+## Event-Driven Communication
+
+**Achieves:** Independent evolution
+
+Services communicate by publishing events, not calling each other directly.
+
+**Core concepts:**
+- **Publish events** when something important happens
+- **Subscribe to events** you care about
+- **No direct dependencies** between publisher and subscriber
+- **Eventual consistency** - accept that not everything updates instantly
+
+**Why this matters:**
+- Add new services without changing existing ones
+- Services can be deployed independently
+- Natural resilience - if a subscriber is down, events queue
+
+**Trade-offs:**
+- Harder to trace request flow
+- Eventual consistency requires different thinking
+- Need infrastructure for reliable event delivery
+
+## Commands and Events
+
+**Achieves:** Explicit over implicit
+
+Distinguish between requests (commands) and facts (events).
+
+**Core concepts:**
+- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
+- Commands can be rejected (validation, business rules)
+- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
+- Events are immutable - what happened, happened
+
+**Why this matters:**
+- Clear separation of "trying to do X" vs "X happened"
+- Commands validate, events just record
+- Enables replay - reprocess events with new logic
+
+## When to Diverge
+
+These patterns are defaults, not mandates. Diverge intentionally when:
+
+- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
+- **Performance requires it** - sometimes synchronous calls are necessary
+- **Team context** - patterns the team doesn't understand cause more harm than good
+- **Prototyping** - validate ideas before investing in full architecture
+
+When diverging, document the decision in the project's `vision.md` Architecture section.
+
+## Project-Level Architecture
+
+Each project documents architectural choices in `vision.md`:
+
+```markdown
+## Architecture
+
+This project follows organization architecture patterns.
+
+### Alignment
+- Event sourcing for [which aggregates/domains]
+- Bounded contexts: [list contexts and their responsibilities]
+- Event-driven communication between [which services]
+
+### Intentional Divergences
+| Area | Standard Pattern | What We Do Instead | Why |
+|------|------------------|-------------------|-----|
+```
+
+## Go-Specific Best Practices
+
+### Package Organization
+
+**Good package structure:**
+```
+project/
+├── cmd/                    # Application entry points
+│   └── server/
+│       └── main.go
+├── internal/               # Private packages
+│   ├── domain/             # Core business logic
+│   │   ├── user/
+│   │   └── order/
+│   ├── service/            # Application services
+│   ├── repository/         # Data access
+│   └── handler/            # HTTP/gRPC handlers
+├── pkg/                    # Public, reusable packages
+└── go.mod
+```
+
+**Package naming:**
+- Short, concise, lowercase: `user`, `order`, `auth`
+- Avoid generic names: `util`, `common`, `helpers`, `misc`
+- Name after what it provides, not what it contains
+- One package per concept, not per file
+
+**Package cohesion:**
+- A package should have a single, focused responsibility
+- Package internal files can use internal types freely
+- Minimize exported types - export interfaces, hide implementations
+
+### Interfaces
+
+**Accept interfaces, return structs:**
+```go
+// Good: Accept interface, return concrete type
+func NewUserService(repo UserRepository) *UserService {
+    return &UserService{repo: repo}
+}
+
+// Bad: Accept and return interface
+func NewUserService(repo UserRepository) UserService {
+    return &userService{repo: repo}
+}
+```
+
+**Define interfaces at point of use:**
+```go
+// Good: Interface defined where it's used (consumer owns the interface)
+package service
+
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+
+// Bad: Interface defined with implementation (producer owns the interface)
+package repository
+
+type UserRepository interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+```
+
+**Keep interfaces small:**
+- Prefer single-method interfaces
+- Large interfaces indicate missing abstraction
+- Compose small interfaces when needed
+
+### Error Handling
+
+**Wrap errors with context:**
+```go
+// Good: Wrap with context
+if err != nil {
+    return fmt.Errorf("fetching user %s: %w", id, err)
+}
+
+// Bad: Return bare error
+if err != nil {
+    return err
+}
+```
+
+**Use sentinel errors for expected conditions:**
+```go
+var ErrNotFound = errors.New("not found")
+var ErrConflict = errors.New("conflict")
+
+// Check with errors.Is
+if errors.Is(err, ErrNotFound) {
+    // handle not found
+}
+```
+
+**Error types for rich errors:**
+```go
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("%s: %s", e.Field, e.Message)
+}
+
+// Check with errors.As
+var valErr *ValidationError
+if errors.As(err, &valErr) {
+    // handle validation error
+}
+```
+
+### Dependency Injection
+
+**Constructor injection:**
+```go
+type UserService struct {
+    repo   UserRepository
+    logger Logger
+}
+
+func NewUserService(repo UserRepository, logger Logger) *UserService {
+    return &UserService{
+        repo:   repo,
+        logger: logger,
+    }
+}
+```
+
+**Wire dependencies in main:**
+```go
+func main() {
+    // Create dependencies
+    db := database.Connect()
+    logger := slog.Default()
+
+    // Wire up services
+    userRepo := repository.NewUserRepository(db)
+    userService := service.NewUserService(userRepo, logger)
+    userHandler := handler.NewUserHandler(userService)
+
+    // Start server
+    http.Handle("/users", userHandler)
+    http.ListenAndServe(":8080", nil)
+}
+```
+
+**Avoid global state:**
+- No `init()` for service initialization
+- No package-level variables for dependencies
+- Pass context explicitly, don't store in structs
+
+### Testing
+
+**Table-driven tests:**
+```go
+func TestUserService_Create(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   CreateUserInput
+        want    *User
+        wantErr error
+    }{
+        {
+            name:  "valid user",
+            input: CreateUserInput{Email: "test@example.com"},
+            want:  &User{Email: "test@example.com"},
+        },
+        {
+            name:    "invalid email",
+            input:   CreateUserInput{Email: "invalid"},
+            wantErr: ErrInvalidEmail,
+        },
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            // arrange, act, assert
+        })
+    }
+}
+```
+
+**Test doubles:**
+- Use interfaces for test doubles
+- Prefer hand-written mocks over generated ones for simple cases
+- Use `testify/mock` or `gomock` for complex mocking needs
+
+**Test package naming:**
+- `package user_test` for black-box testing (preferred)
+- `package user` for white-box testing when needed
+
+## Generic Architecture Patterns
+
+### Layered Architecture
+
+```
+┌─────────────────────────────────┐
+│         Presentation            │  HTTP handlers, CLI, gRPC
+├─────────────────────────────────┤
+│         Application             │  Use cases, orchestration
+├─────────────────────────────────┤
+│           Domain                │  Business logic, entities
+├─────────────────────────────────┤
+│        Infrastructure           │  Database, external services
+└─────────────────────────────────┘
+```
+
+**Rules:**
+- Dependencies point downward only
+- Upper layers depend on interfaces, not implementations
+- Domain layer has no external dependencies
+
+### SOLID Principles
+
+**Single Responsibility (S):**
+- Each module has one reason to change
+- Split code that changes for different reasons
+
+**Open/Closed (O):**
+- Open for extension, closed for modification
+- Add new behavior through new types, not changing existing ones
+
+**Liskov Substitution (L):**
+- Subtypes must be substitutable for their base types
+- Interfaces should be implementable without surprises
+
+**Interface Segregation (I):**
+- Clients shouldn't depend on interfaces they don't use
+- Prefer many small interfaces over few large ones
+
+**Dependency Inversion (D):**
+- High-level modules shouldn't depend on low-level modules
+- Both should depend on abstractions
+
+### Dependency Direction
+
+```
+                    ┌──────────────┐
+                    │    Domain    │
+                    │  (no deps)   │
+                    └──────────────┘
+                           ▲
+              ┌────────────┴────────────┐
+              │                         │
+      ┌───────┴───────┐         ┌───────┴───────┐
+      │  Application  │         │Infrastructure │
+      │ (uses domain) │         │(implements    │
+      └───────────────┘         │ domain intf)  │
+              ▲                 └───────────────┘
+              │
+      ┌───────┴───────┐
+      │ Presentation  │
+      │(calls app)    │
+      └───────────────┘
+```
+
+**Key insight:** Infrastructure implements domain interfaces, doesn't define them. This inverts the "natural" dependency direction.
+
+### Module Boundaries
+
+**Signs of good boundaries:**
+- Modules can be understood in isolation
+- Changes are localized within modules
+- Clear, minimal public API
+- Dependencies flow in one direction
+
+**Signs of bad boundaries:**
+- Circular dependencies between modules
+- "Shotgun surgery" - small changes require many file edits
+- Modules reach into each other's internals
+- Unclear ownership of concepts
+
+## Repository Health Indicators
+
+### Positive Indicators
+
+| Indicator | What to Look For |
+|-----------|------------------|
+| Clear structure | Obvious package organization, consistent naming |
+| Small interfaces | Most interfaces have 1-3 methods |
+| Explicit dependencies | Constructor injection, no globals |
+| Test coverage | Unit tests for business logic, integration tests for boundaries |
+| Error handling | Wrapped errors, typed errors for expected cases |
+| Documentation | CLAUDE.md accurate, code comments explain "why" |
+
+### Warning Signs
+
+| Indicator | What to Look For |
+|-----------|------------------|
+| God packages | `utils/`, `common/`, `helpers/` with 20+ files |
+| Circular deps | Package A imports B, B imports A |
+| Deep nesting | 4+ levels of directory nesting |
+| Huge files | Files with 500+ lines |
+| Interface pollution | Interfaces for everything, even single implementations |
+| Global state | Package-level variables, `init()` for setup |
+
+### Metrics to Track
+
+- **Package fan-out:** How many packages does each package import?
+- **Cyclomatic complexity:** How complex are the functions?
+- **Test coverage:** What percentage of code is tested?
+- **Import depth:** How deep is the import tree?
+
+## Review Checklists
+
+### Repository Audit Checklist
+
+Use this when evaluating overall repository health.
+
+**Structure:**
+- [ ] Clear package organization following Go conventions
+- [ ] No circular dependencies between packages
+- [ ] Appropriate use of `internal/` for private packages
+- [ ] `cmd/` for application entry points
+
+**Dependencies:**
+- [ ] Dependencies flow inward (toward domain)
+- [ ] Interfaces defined at point of use (not with implementation)
+- [ ] No global state or package-level dependencies
+- [ ] Constructor injection throughout
+
+**Code Quality:**
+- [ ] Consistent naming conventions
+- [ ] No "god" packages (utils, common, helpers)
+- [ ] Errors wrapped with context
+- [ ] Small, focused interfaces
+
+**Testing:**
+- [ ] Unit tests for domain logic
+- [ ] Integration tests for boundaries (DB, HTTP)
+- [ ] Tests are readable and maintainable
+- [ ] Test coverage for critical paths
+
+**Documentation:**
+- [ ] CLAUDE.md is accurate and helpful
+- [ ] vision.md explains the product purpose
+- [ ] Code comments explain "why", not "what"
+
+### Issue Refinement Checklist
+
+Use this when reviewing issues for architecture impact.
+
+**Scope:**
+- [ ] Issue is a vertical slice (user-visible value)
+- [ ] Changes are localized to specific packages
+- [ ] No cross-cutting concerns hidden in implementation
+
+**Design:**
+- [ ] Follows existing patterns in the codebase
+- [ ] New abstractions are justified
+- [ ] Interface changes are backward compatible (or breaking change is documented)
+
+**Dependencies:**
+- [ ] New dependencies are minimal and justified
+- [ ] No new circular dependencies introduced
+- [ ] Integration points are clearly defined
+
+**Testability:**
+- [ ] Acceptance criteria are testable
+- [ ] New code can be unit tested in isolation
+- [ ] Integration test requirements are clear
+
+### PR Review Checklist
+
+Use this when reviewing pull requests for architecture concerns.
+
+**Structure:**
+- [ ] Changes respect existing package boundaries
+- [ ] New packages follow naming conventions
+- [ ] No new circular dependencies
+
+**Interfaces:**
+- [ ] Interfaces are defined where used
+- [ ] Interfaces are minimal and focused
+- [ ] Breaking interface changes are justified
+
+**Dependencies:**
+- [ ] Dependencies injected via constructors
+- [ ] No new global state
+- [ ] External dependencies properly abstracted
+
+**Error Handling:**
+- [ ] Errors wrapped with context
+- [ ] Sentinel errors for expected conditions
+- [ ] Error types for rich error information
+
+**Testing:**
+- [ ] New code has appropriate test coverage
+- [ ] Tests are clear and maintainable
+- [ ] Edge cases covered
+
+## Anti-Patterns to Flag
+
+### God Packages
+
+**Problem:** Packages like `utils/`, `common/`, `helpers/` become dumping grounds.
+
+**Symptoms:**
+- 20+ files in one package
+- Unrelated functions grouped together
+- Package imported by everything
+
+**Fix:** Extract cohesive packages based on what they provide: `validation`, `httputil`, `timeutil`.
+
+### Circular Dependencies
+
+**Problem:** Package A imports B, and B imports A (directly or transitively).
+
+**Symptoms:**
+- Import cycle compile errors
+- Difficulty understanding code flow
+- Changes cascade unexpectedly
+
+**Fix:**
+- Extract shared types to a third package
+- Use interfaces to invert dependency
+- Merge packages if truly coupled
+
+### Leaky Abstractions
+
+**Problem:** Implementation details leak through abstraction boundaries.
+
+**Symptoms:**
+- Database types in domain layer
+- HTTP types in service layer
+- Framework types in business logic
+
+**Fix:** Define types at each layer, map between them explicitly.
+
+### Anemic Domain Model
+
+**Problem:** Domain objects are just data containers, logic is elsewhere.
+
+**Symptoms:**
+- Domain types have only getters/setters
+- All logic in "service" classes
+- Domain types can be in invalid states
+
+**Fix:** Put behavior with data. Domain types should enforce their own invariants.
+
+### Shotgun Surgery
+
+**Problem:** Small changes require editing many files across packages.
+
+**Symptoms:**
+- Feature adds touch 10+ files
+- Similar changes in multiple places
+- Copy-paste between packages
+
+**Fix:** Consolidate related code. If things change together, they belong together.
+
+### Feature Envy
+
+**Problem:** Code in one package is more interested in another package's data.
+
+**Symptoms:**
+- Many calls to another package's methods
+- Pulling data just to compute something
+- Logic that belongs elsewhere
+
+**Fix:** Move the code to where the data lives, or extract the behavior to a shared place.
+
+### Premature Abstraction
+
+**Problem:** Creating interfaces and abstractions before they're needed.
+
+**Symptoms:**
+- Interfaces with single implementations
+- "Factory" and "Manager" classes everywhere
+- Configuration for things that never change
+
+**Fix:** Write concrete code first. Extract abstractions when you have multiple implementations or need to break dependencies.
+
+### Deep Hierarchy
+
+**Problem:** Excessive layers of abstraction or inheritance.
+
+**Symptoms:**
+- 5+ levels of embedding/composition
+- Hard to trace code flow
+- Changes require understanding many layers
+
+**Fix:** Prefer composition over inheritance. Flatten hierarchies where possible.

skills/vision-management/SKILL.md

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

software-architecture.md

@@ -0,0 +1,130 @@
+# Software Architecture
+
+> **For Claude:** This content is mirrored in `skills/software-architecture/SKILL.md` which is auto-triggered when relevant. You don't need to load this file directly.
+
+This document describes the architectural patterns we use to achieve our [architecture beliefs](./manifesto.md#architecture-beliefs). It serves as human-readable organizational documentation.
+
+## Beliefs to Patterns
+
+| Belief | Primary Pattern | Supporting Patterns |
+|--------|-----------------|---------------------|
+| Auditability by default | Event Sourcing | Immutable events, temporal queries |
+| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
+| Independent evolution | Event-driven communication | Bounded contexts, published language |
+| Explicit over implicit | Commands and Events | Domain events, clear intent |
+
+## Event Sourcing
+
+**Achieves:** Auditability by default
+
+Instead of storing current state, we store the sequence of events that led to it.
+
+**Core concepts:**
+- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
+- **State** is derived by replaying events, not stored directly
+- **Event store** is append-only - history is never modified
+
+**Why this matters:**
+- Complete audit trail for free
+- Debug by replaying history
+- Answer "what was the state at time X?"
+- Recover from bugs by fixing logic and replaying
+
+**Trade-offs:**
+- More complex than CRUD for simple cases
+- Requires thinking in events, not state
+- Eventually consistent read models
+
+## Domain-Driven Design
+
+**Achieves:** Business language in code
+
+The domain model reflects how the business thinks and talks.
+
+**Core concepts:**
+- **Ubiquitous language** - same terms in code, conversations, and documentation
+- **Bounded contexts** - explicit boundaries where terms have consistent meaning
+- **Aggregates** - clusters of objects that change together, with one root entity
+- **Domain events** - capture what happened in business terms
+
+**Why this matters:**
+- Domain experts can read and validate the model
+- New team members learn the domain through code
+- Changes in business rules map clearly to code changes
+
+**Trade-offs:**
+- Upfront investment in understanding the domain
+- Boundaries may need to shift as understanding grows
+- Overkill for pure technical/infrastructure code
+
+## Event-Driven Communication
+
+**Achieves:** Independent evolution
+
+Services communicate by publishing events, not calling each other directly.
+
+**Core concepts:**
+- **Publish events** when something important happens
+- **Subscribe to events** you care about
+- **No direct dependencies** between publisher and subscriber
+- **Eventual consistency** - accept that not everything updates instantly
+
+**Why this matters:**
+- Add new services without changing existing ones
+- Services can be deployed independently
+- Natural resilience - if a subscriber is down, events queue
+
+**Trade-offs:**
+- Harder to trace request flow
+- Eventual consistency requires different thinking
+- Need infrastructure for reliable event delivery
+
+## Commands and Events
+
+**Achieves:** Explicit over implicit
+
+Distinguish between requests (commands) and facts (events).
+
+**Core concepts:**
+- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
+- Commands can be rejected (validation, business rules)
+- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
+- Events are immutable - what happened, happened
+
+**Why this matters:**
+- Clear separation of "trying to do X" vs "X happened"
+- Commands validate, events just record
+- Enables replay - reprocess events with new logic
+
+## When to Diverge
+
+These patterns are defaults, not mandates. Diverge intentionally when:
+
+- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
+- **Performance requires it** - sometimes synchronous calls are necessary
+- **Team context** - patterns the team doesn't understand cause more harm than good
+- **Prototyping** - validate ideas before investing in full architecture
+
+When diverging, document the decision in the project's vision.md (see below).
+
+## Project-Level Architecture
+
+Each project should document its architectural choices in `vision.md` under an **Architecture** section:
+
+```markdown
+## Architecture
+
+This project follows organization architecture patterns.
+
+### Alignment
+- Event sourcing for [which aggregates/domains]
+- Bounded contexts: [list contexts and their responsibilities]
+- Event-driven communication between [which services]
+
+### Intentional Divergences
+| Area | Standard Pattern | What We Do Instead | Why |
+|------|------------------|-------------------|-----|
+| [area] | [expected pattern] | [actual approach] | [reasoning] |
+```
+
+This creates traceability: org beliefs → patterns → project decisions.