Add vertical vs horizontal slicing guidance

Adds guidance to prefer vertical slices (user-visible value) over
horizontal slices (technical layers) when planning and writing issues.

roadmap-planning skill:
- New "Vertical vs Horizontal Slices" section
- Demo test: "Can a user demo/test this independently?"
- Good vs bad examples table
- When horizontal slices are acceptable

issue-writing skill:
- New "Vertical Slices" section
- Demo test guidance
- Good vs bad issue titles table
- User-focused issue framing examples

Closes #31

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

.gitignore

@@ -16,11 +16,3 @@
 secrets/
 *.pem
 *.key
-
-# opencode
-.opencode/opencode.json
-.opencode/package-lock.json
-
-node_modules
-bun.lock
-package-lock.json

.opencode/tools/git-worktree-create.ts

@@ -1,13 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Create a git worktree for a branch or PR",
-  args: {
-    branch: tool.schema.string().describe("Branch name or PR number"),
-  },
-  async execute(args) {
-    const result = await $`git worktree add ../worktrees/${args.branch}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-actions-runs-list.ts

@@ -1,23 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "List workflow runs for Gitea actions with optional filters",
-  args: {
-    status: tool.schema.string().optional().describe("Filter by status (success, failure, pending, queued, in_progress, skipped, canceled)"),
-    branch: tool.schema.string().optional().describe("Filter by branch name"),
-    event: tool.schema.string().optional().describe("Filter by event type (push, pull_request, etc.)"),
-    limit: tool.schema.number().optional().describe("Number of results to return (default: 30)"),
-    since: tool.schema.string().optional().describe("Show runs started after this time (e.g., '24h', '7d')"),
-  },
-  async execute(args) {
-    let cmd = [`tea`, `actions`, `runs`, `list`, `-o`, `json`]
-    if (args.status) cmd = [...cmd, `--status`, args.status]
-    if (args.branch) cmd = [...cmd, `--branch`, args.branch]
-    if (args.event) cmd = [...cmd, `--event`, args.event]
-    if (args.limit) cmd = [...cmd, `--limit`, String(args.limit)]
-    if (args.since) cmd = [...cmd, `--since`, args.since]
-    const result = await $`${cmd}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-actions-runs-logs.ts

@@ -1,17 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Get logs for a specific Gitea actions workflow run to diagnose failures",
-  args: {
-    runId: tool.schema.number().describe("Workflow run ID to get logs for"),
-    job: tool.schema.string().optional().describe("Specific job ID to view (if omitted, shows all jobs)"),
-  },
-  async execute(args) {
-    let cmd = [`tea`, `actions`, `runs`, `logs`]
-    if (args.job) cmd = [...cmd, `--job`, args.job]
-    cmd = [...cmd, String(args.runId), `-o`, `simple`]
-    const result = await $`${cmd}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-comment.ts

@@ -1,14 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Add a comment to a specific issue using tea CLI",
-  args: {
-    issueNumber: tool.schema.number().describe("Issue number/index"),
-    body: tool.schema.string().describe("Comment body"),
-  },
-  async execute(args) {
-    const result = await $`tea comment ${args.issueNumber} ${args.body}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-issue-create.ts

@@ -1,14 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Create a new issue in the GitHub repository using tea CLI",
-  args: {
-    title: tool.schema.string().describe("Issue title"),
-    description: tool.schema.string().optional().describe("Issue description (supports markdown)"),
-  },
-  async execute(args) {
-    const result = await $`tea issues create -t ${args.title} -d ${args.description}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-issue-get.ts

@@ -1,13 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Get a specific issue with all details and comments using tea CLI",
-  args: {
-    issueNumber: tool.schema.number().describe("Issue number/index"),
-  },
-  async execute(args) {
-    const result = await $`tea issues ${args.issueNumber} --comments --output json`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-issues.ts

@@ -1,11 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "List all issues in the project using tea CLI",
-  args: {},
-  async execute(args, context) {
-    const result = await $`tea issues list`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-pr-create.ts

@@ -1,24 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Create a pull request in the repository using tea CLI",
-  args: {
-    title: tool.schema.string().describe("PR title"),
-    head: tool.schema.string().optional().describe("Branch name of the PR source (defaults to current branch)"),
-    base: tool.schema.string().optional().describe("Branch name of the PR target (defaults to repository default branch)"),
-    description: tool.schema.string().optional().describe("PR description (supports markdown)"),
-    assignees: tool.schema.string().optional().describe("Comma-separated list of usernames to assign"),
-    labels: tool.schema.string().optional().describe("Comma-separated list of labels to assign"),
-  },
-  async execute(args) {
-    let cmd = [`tea`, `pulls`, `create`, `-t`, args.title]
-    if (args.head) cmd = [...cmd, `--head`, args.head]
-    if (args.base) cmd = [...cmd, `-b`, args.base]
-    if (args.description) cmd = [...cmd, `-d`, args.description]
-    if (args.assignees) cmd = [...cmd, `-a`, args.assignees]
-    if (args.labels) cmd = [...cmd, `-L`, args.labels]
-    const result = await $`${cmd}`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-pr-get.ts

@@ -1,13 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "Get a specific pull request with all details and comments using tea CLI",
-  args: {
-    pullNumber: tool.schema.number().describe("Pull request number/index"),
-  },
-  async execute(args) {
-    const result = await $`tea pulls ${args.pullNumber} --comments --output json`.text()
-    return result.trim()
-  },
-})

.opencode/tools/tea-pulls.ts

@@ -1,14 +0,0 @@
-import { tool } from "@opencode-ai/plugin"
-import { $ } from "bun"
-
-export default tool({
-  description: "List pull requests in the repository using tea CLI",
-  args: {
-    state: tool.schema.string().optional().describe("Filter by state (all|open|closed)"),
-  },
-  async execute(args) {
-    const state = args.state || "open"
-    const result = await $`tea pulls --state ${state} --output json`.text()
-    return result.trim()
-  },
-})

ARCHITECTURE.md

@@ -0,0 +1,426 @@
+# Architecture
+
+This document explains how the three component types—Commands, Skills, and Agents—work together to create a composable AI workflow system.
+
+## Overview
+
+The architecture follows a layered composition model where each component type serves a distinct purpose:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         USER                                    │
+│                           │                                     │
+│                           ▼                                     │
+│  ┌─────────────────────────────────────────────────────────┐   │
+│  │                      COMMANDS                            │   │
+│  │           User-facing entry points                       │   │
+│  │   /work-issue  /dashboard  /plan-issues  /groom         │   │
+│  └─────────────────────────────────────────────────────────┘   │
+│                           │                                     │
+│              ┌────────────┼────────────┐                       │
+│              ▼            ▼            ▼                       │
+│  ┌─────────────────┐ ┌─────────────────────────────────────┐   │
+│  │     AGENTS      │ │              SKILLS                  │   │
+│  │  Specialized    │ │         Knowledge modules            │   │
+│  │   subagents     │ │                                      │   │
+│  │                 │ │  issue-writing    gitea            │   │
+│  │ product-manager │ │  backlog-grooming roadmap-planning   │   │
+│  └─────────────────┘ └─────────────────────────────────────┘   │
+│              │                    ▲                            │
+│              └────────────────────┘                            │
+│                   Agents use skills                            │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Components
+
+### Commands
+
+**Location:** `commands/*.md`
+
+Commands are user-facing entry points that trigger workflows. They define *what* to do, not *how* to do it.
+
+#### Structure
+
+Each command file contains:
+- **Frontmatter**: Metadata including description and argument hints
+- **Instructions**: Step-by-step workflow for Claude to follow
+- **Tool references**: Which CLI tools or skills to invoke
+
+```yaml
+---
+description: Work on a Gitea issue
+argument-hint: <issue-number>
+---
+
+# Work on Issue #$1
+
+1. **View the issue**: `tea issues $1`
+2. **Create a branch**: `git checkout -b issue-$1-<title>`
+...
+```
+
+#### Characteristics
+
+- **Invoked explicitly** by users via `/command-name`
+- **Self-contained workflows** with clear start and end
+- **May use skills** for domain knowledge
+- **May spawn agents** for complex subtasks
+- **Request approval** before significant actions
+
+#### When to Create a Command
+
+Create a command when you have:
+- A repeatable workflow with clear steps
+- User-initiated action (not automatic)
+- Need for consistent behavior across sessions
+
+#### Current Commands
+
+| Command | Purpose | Skills Used |
+|---------|---------|-------------|
+| `/work-issue` | Implement an issue end-to-end | gitea |
+| `/dashboard` | View open issues and PRs | gitea |
+| `/review-pr` | Review and act on a PR | gitea |
+| `/create-issue` | Create single or batch issues | gitea, issue-writing |
+| `/groom` | Improve issue quality | backlog-grooming, issue-writing |
+| `/roadmap` | View issues organized by status | gitea, roadmap-planning |
+| `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, gitea |
+
+---
+
+### Skills
+
+**Location:** `skills/<skill-name>/SKILL.md`
+
+Skills are knowledge modules—focused documents that teach Claude how to do something well. They encode domain expertise and best practices.
+
+#### Structure
+
+Each skill file contains:
+- **Conceptual knowledge**: What Claude needs to understand
+- **Patterns and templates**: Reusable structures
+- **Guidelines and checklists**: Quality standards
+- **Examples**: Concrete illustrations
+
+```markdown
+# Issue Writing
+
+How to write clear, actionable issues.
+
+## Issue Structure
+### Title
+- Start with action verb: "Add", "Fix", "Update"
+- Be specific: "Add user authentication" not "Auth stuff"
+...
+```
+
+#### Characteristics
+
+- **Passive knowledge** that doesn't act on its own
+- **Focused scope**: one domain, one concern
+- **Composable**: multiple skills can be combined
+- **Referenced** by commands and agents
+- **No side effects**: information only
+
+#### When to Create a Skill
+
+Create a skill when you find yourself:
+- Explaining the same concepts repeatedly
+- Wanting consistent quality in a specific area
+- Building up domain expertise that should persist
+
+#### Current Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `gitea` | How to use the Gitea CLI for issues and PRs |
+| `issue-writing` | How to structure clear, actionable issues |
+| `backlog-grooming` | How to review and improve existing issues |
+| `roadmap-planning` | How to plan features and create issue breakdowns |
+| `code-review` | How to review code for quality, bugs, security, and style |
+
+---
+
+### Agents
+
+**Location:** `agents/<agent-name>/AGENT.md`
+
+Agents are specialized subagents that combine multiple skills into focused personas. They can work autonomously on complex tasks with isolated context.
+
+#### Structure
+
+Each agent file uses YAML frontmatter followed by a system prompt:
+
+```markdown
+---
+name: agent-name
+description: When this agent should be invoked (used for automatic delegation)
+model: inherit
+skills: skill1, skill2, skill3
+---
+
+You are a [role] specializing in [domain].
+
+## Capabilities
+
+You can:
+- Do thing one
+- Do thing two
+
+## Behavior
+
+- Guideline one
+- Guideline two
+```
+
+#### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, hyphens) |
+| `description` | Yes | When to use this agent (enables auto-delegation) |
+| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit` |
+| `skills` | No | Comma-separated skill names to auto-load |
+| `tools` | No | Limit available tools (inherits all if omitted) |
+
+#### Characteristics
+
+- **Isolated context**: Each agent maintains separate conversation state
+- **Skill composition**: Combines multiple skills for complex tasks
+- **Autonomous operation**: Can work with minimal intervention
+- **Spawned by commands**: Commands decide when to use agents
+- **Returns results**: Reports back to the main conversation
+
+#### When to Create an Agent
+
+Create an agent when you need:
+- To combine multiple skills for a role
+- Parallel processing of independent tasks
+- Isolated context to prevent pollution
+- Autonomous handling of complex workflows
+
+#### Current Agents
+
+| Agent | Skills | Use Case |
+|-------|--------|----------|
+| `product-manager` | gitea, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning |
+| `code-reviewer` | gitea, code-review | Automated PR review, quality checks |
+
+---
+
+## Data and Control Flow
+
+### Invocation Flow
+
+```
+User invokes command
+        │
+        ▼
+┌───────────────────┐
+│ Command executes  │
+│ workflow steps    │
+└───────────────────┘
+        │
+        ├─── Direct action (git, tea CLI)
+        │
+        ├─── Reference skill for knowledge
+        │           │
+        │           ▼
+        │    ┌─────────────────┐
+        │    │ Skill provides  │
+        │    │ patterns and    │
+        │    │ guidelines      │
+        │    └─────────────────┘
+        │
+        └─── Spawn agent for complex subtask
+                    │
+                    ▼
+             ┌─────────────────┐
+             │ Agent works     │
+             │ autonomously    │
+             │ with its skills │
+             └─────────────────┘
+                    │
+                    ▼
+             Results return to command
+```
+
+### Example: `/plan-issues add dark mode`
+
+1. **Command invoked**: User runs `/plan-issues add dark mode`
+
+2. **Skills consulted**:
+   - `roadmap-planning`: How to break down features
+   - `issue-writing`: How to structure each issue
+   - `gitea`: How to create issues via CLI
+
+3. **Workflow executed**:
+   - Analyze what "dark mode" involves
+   - Break down into discrete issues
+   - Present plan for approval
+   - Create issues in dependency order
+
+4. **Output**: Issues created with proper structure and references
+
+### Example: `/groom` (batch mode)
+
+1. **Command invoked**: User runs `/groom` with no argument
+
+2. **Skills consulted**:
+   - `backlog-grooming`: Checklist and evaluation criteria
+   - `issue-writing`: Standards for improvements
+
+3. **Potential agent spawn**: For many issues, could spawn `product-manager` agent
+
+4. **Agent workflow**:
+   - Fetches all open issues
+   - Evaluates each against grooming checklist
+   - Categorizes as ready/needs-work/stale
+   - Proposes improvements
+
+5. **Output**: Summary table with suggestions, optional issue updates
+
+---
+
+## Component Relationships
+
+### How Commands Use Skills
+
+Commands reference skills by name in their instructions:
+
+```markdown
+# Groom Issues
+
+Use the backlog-grooming and issue-writing skills.
+```
+
+Claude reads the referenced skill files to gain the necessary knowledge before executing the command workflow.
+
+### How Agents Use Skills
+
+Agents declare their skills in the YAML frontmatter:
+
+```yaml
+---
+name: product-manager
+skills: gitea, issue-writing, backlog-grooming
+---
+```
+
+When spawned, the agent has access to all listed skills as part of its context.
+
+### How Commands Spawn Agents
+
+Commands can delegate to agents for complex subtasks:
+
+```markdown
+For comprehensive backlog review, spawn the product-manager agent.
+```
+
+The agent works autonomously and returns results to the command.
+
+---
+
+## Design Principles
+
+### Separation of Concerns
+
+- **Commands**: Define workflows (what to do)
+- **Skills**: Encode knowledge (how to do it well)
+- **Agents**: Execute complex tasks (who does it)
+
+### Composability
+
+Small, focused components combine to handle complex scenarios:
+
+```
+/plan-issues = roadmap-planning + issue-writing + gitea
+product-manager = all four skills combined
+```
+
+### Single Responsibility
+
+Each component has one clear purpose:
+- One command = one workflow
+- One skill = one domain
+- One agent = one role
+
+### Progressive Enhancement
+
+Start simple, add complexity as needed:
+1. Use skills directly for simple tasks
+2. Create commands for repeatable workflows
+3. Add agents for complex parallel work
+
+---
+
+## File Structure
+
+```
+ai/
+├── commands/                    # User-invoked workflows
+│   ├── work-issue.md
+│   ├── dashboard.md
+│   ├── review-pr.md
+│   ├── create-issue.md
+│   ├── groom.md
+│   ├── roadmap.md
+│   └── plan-issues.md
+├── skills/                      # Knowledge modules
+│   ├── gitea/
+│   │   └── SKILL.md
+│   ├── issue-writing/
+│   │   └── SKILL.md
+│   ├── backlog-grooming/
+│   │   └── SKILL.md
+│   ├── roadmap-planning/
+│   │   └── SKILL.md
+│   └── code-review/
+│       └── SKILL.md
+├── agents/                      # Specialized subagents
+│   ├── product-manager/
+│   │   └── AGENT.md
+│   └── code-reviewer/
+│       └── AGENT.md
+├── scripts/                     # Hook scripts
+│   └── pre-commit-checks.sh
+├── settings.json                # Claude Code configuration
+├── CLAUDE.md                    # Project instructions
+├── VISION.md                    # Why this project exists
+└── ARCHITECTURE.md              # This document
+```
+
+---
+
+## Adding New Components
+
+### Adding a Command
+
+1. Create `commands/<name>.md`
+2. Add frontmatter with description and argument hints
+3. Define the workflow steps
+4. Reference any needed skills
+5. Test the workflow
+
+### Adding a Skill
+
+1. Create `skills/<name>/SKILL.md`
+2. Document the domain knowledge
+3. Include patterns, templates, and examples
+4. Reference from commands or agents as needed
+
+### Adding an Agent
+
+1. Create `agents/<name>/AGENT.md`
+2. Add YAML frontmatter with `name`, `description`, and `skills`
+3. Write system prompt defining capabilities and behavior
+4. Update commands to use the agent where appropriate
+
+---
+
+## See Also
+
+- [VISION.md](VISION.md): The philosophy and goals behind this project
+- [CLAUDE.md](CLAUDE.md): Setup and configuration instructions
+- [README.md](README.md): Project overview and quick start

CLAUDE.md

@@ -0,0 +1,105 @@
+# Architecture
+
+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/architecture.git
+cd architecture
+make install
+```
+
+## What This Repo Contains
+
+| Component | Purpose |
+|-----------|---------|
+| `manifesto.md` | Organization vision, personas, beliefs, principles |
+| `learnings/` | Historical record and governance |
+| `commands/` | AI workflow entry points (/work-issue, /manifesto, etc.) |
+| `skills/` | Tool and practice knowledge |
+| `agents/` | Focused subtask handlers |
+| `settings.json` | Claude Code configuration |
+| `Makefile` | Install symlinks to ~/.claude/ |
+
+## Project Structure
+
+```
+architecture/
+├── manifesto.md    # Organization vision and beliefs
+├── learnings/      # Captured learnings and governance
+├── commands/       # Slash commands (/work-issue, /dashboard)
+├── skills/         # Knowledge modules (auto-triggered)
+├── agents/         # Focused subtask handlers (isolated context)
+├── scripts/        # Hook scripts (pre-commit, token loading)
+├── settings.json   # Claude Code settings
+└── Makefile        # Install/uninstall symlinks
+```
+
+All files symlink to `~/.claude/` via `make install`.
+
+## Two Levels of Vision
+
+| Level | Document | Command | Purpose |
+|-------|----------|---------|---------|
+| Organization | `manifesto.md` | `/manifesto` | Who we are, shared personas, beliefs |
+| Product | `vision.md` | `/vision` | Product-specific direction and goals |
+
+See the manifesto for our identity, personas, and beliefs about AI-augmented development.
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/manifesto` | View/manage organization manifesto |
+| `/vision` | View/manage product vision and milestones |
+| `/work-issue <n>` | Fetch issue, create branch, implement, create PR |
+| `/dashboard` | Show open issues and PRs |
+| `/review-pr <n>` | Review PR with diff and comments |
+| `/create-issue` | Create single or batch issues |
+| `/retro` | Capture learnings as issues for encoding |
+| `/plan-issues` | Break down features into issues |
+| `/groom` | Improve issue quality |
+
+## Gitea Integration
+
+Uses `tea` CLI for issue/PR management:
+
+```bash
+# Setup (one-time)
+brew install tea
+tea logins add --name flowmade --url https://git.flowmade.one --token <your-token>
+
+# Create token at: https://git.flowmade.one/user/settings/applications
+```
+
+## Architecture Components
+
+### Skills
+Knowledge modules that teach Claude how to do something.
+
+- **Purpose**: Encode best practices and tool knowledge
+- **Location**: `skills/<name>/SKILL.md`
+- **Usage**: Referenced by commands via `@~/.claude/skills/xxx/SKILL.md`
+
+### 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

Makefile

@@ -1,71 +1,54 @@
-.PHONY: install uninstall status start-llm stop-llm restart-llm
+.PHONY: install uninstall status
 
-OPENCODE_DIR := $(HOME)/.config/opencode
+CLAUDE_DIR := $(HOME)/.claude
 REPO_DIR := $(shell pwd)
 
 # Items to symlink
-ITEMS := skills tools agents
-
-# LLM services to manage
-LLM_SERVICES := odin
-
-PLIST_PATH := ~/Library/LaunchAgents
+ITEMS := commands scripts skills agents settings.json
 
 install:
-	@echo "Installing OpenCode config symlinks..."
-	@mkdir -p $(OPENCODE_DIR)
+	@echo "Installing Claude Code config symlinks..."
+	@mkdir -p $(CLAUDE_DIR)
 	@for item in $(ITEMS); do \
-		if [ -e "$(REPO_DIR)/.opencode/$$item" ]; then \
-			if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
+		if [ -e "$(REPO_DIR)/$$item" ]; then \
+			if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
 				echo "  $$item: already symlinked"; \
+			elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
+				echo "  $$item: backing up existing to $$item.bak"; \
+				mv "$(CLAUDE_DIR)/$$item" "$(CLAUDE_DIR)/$$item.bak"; \
+				ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
+				echo "  $$item: symlinked"; \
 			else \
-				ln -s "$(REPO_DIR)/.opencode/$$item" "$(OPENCODE_DIR)/$$item"; \
+				ln -s "$(REPO_DIR)/$$item" "$(CLAUDE_DIR)/$$item"; \
 				echo "  $$item: symlinked"; \
 			fi \
-		else \
-			echo "  $$item: skipped (not found)"; \
 		fi \
 	done
-	@echo "Done!"
+	@echo "Done! Restart Claude Code to apply changes."
 
 uninstall:
-	@echo "Removing OpenCode config symlinks..."
+	@echo "Removing Claude Code config symlinks..."
 	@for item in $(ITEMS); do \
-		if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
-			rm "$(OPENCODE_DIR)/$$item"; \
+		if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
+			rm "$(CLAUDE_DIR)/$$item"; \
 			echo "  $$item: removed symlink"; \
+			if [ -e "$(CLAUDE_DIR)/$$item.bak" ]; then \
+				mv "$(CLAUDE_DIR)/$$item.bak" "$(CLAUDE_DIR)/$$item"; \
+				echo "  $$item: restored backup"; \
+			fi \
 		fi \
 	done
 	@echo "Done!"
 
 status:
-	@echo "OpenCode config status:"
+	@echo "Claude Code config status:"
 	@for item in $(ITEMS); do \
-		if [ -L "$(OPENCODE_DIR)/$$item" ]; then \
-			target=$$(readlink "$(OPENCODE_DIR)/$$item"); \
+		if [ -L "$(CLAUDE_DIR)/$$item" ]; then \
+			target=$$(readlink "$(CLAUDE_DIR)/$$item"); \
 			echo "  $$item: symlink -> $$target"; \
-		elif [ -e "$(OPENCODE_DIR)/$$item" ]; then \
+		elif [ -e "$(CLAUDE_DIR)/$$item" ]; then \
 			echo "  $$item: exists (not symlinked)"; \
 		else \
 			echo "  $$item: not found"; \
 		fi \
 	done
-
-stop-llm-%:
-	@echo "Stopping com.vllm-mlx-$*..."
-	@launchctl bootout gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist 2>/dev/null || true
-
-stop-llm: $(patsubst %,stop-llm-%,$(LLM_SERVICES))
-
-start-llm-%:
-	@echo "Starting com.vllm-mlx-$*..."
-	@launchctl bootstrap gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist
-
-start-llm: $(patsubst %,start-llm-%,$(LLM_SERVICES))
-
-restart-llm-%:
-	@echo "Restarting com.vllm-mlx-$*..."
-	@launchctl bootout gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist || true
-	@launchctl bootstrap gui/$$(id -u) $(PLIST_PATH)/com.vllm-mlx.$*.plist
-
-restart-llm: $(patsubst %,restart-llm-%,$(LLM_SERVICES))

README.md

@@ -1,21 +1,56 @@
 # Architecture
 
-The organizational source of truth for how we build software with OpenCode.
+The organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.
 
-This repository contains the structure for our OpenCode configuration: skills, tools, and agents that make AI-assisted development predictable and effective.
+A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
+
+## Why This Project?
+
+Claude Code is powerful, but its effectiveness depends on how you use it. This project provides:
+
+- **Structured workflows** for common development tasks (issue tracking, PR reviews, planning)
+- **Composable components** that build on each other (skills, agents, commands)
+- **Forgejo integration** for seamless issue and PR management
+- **Consistent patterns** that make AI assistance more predictable and effective
 
 ## Core Concepts
 
-OpenCode uses three component types:
+The project is built around three composable component types:
 
-| Component | Location | Purpose | Example |
-|-----------|----------|---------|---------|
-| **Skills** | `.opencode/skills/` | Reference knowledge | `issue-writing` knows how to structure good issues |
-| **Tools** | `.opencode/tools/` | Custom functions | `spawn_issues` implements multiple issues in parallel |
-| **Agents** | `.opencode/agents/` | Specialized subagents | `code-reviewer` handles PR reviews |
+```
+┌─────────────────────────────────────────────────────────┐
+│                      COMMANDS                           │
+│         User-facing entry points (/work-issue)          │
+│                         │                               │
+│                         ▼                               │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │                    AGENTS                        │   │
+│  │    Subprocesses with isolated context            │   │
+│  │    (parallel processing, complex workflows)      │   │
+│  │                      │                           │   │
+│  │                      ▼                           │   │
+│  │  ┌───────────────────────────────────────────┐  │   │
+│  │  │                 SKILLS                     │  │   │
+│  │  │   Reusable knowledge modules               │  │   │
+│  │  │   (gitea, issue-writing, planning)       │  │   │
+│  │  └───────────────────────────────────────────┘  │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+| Component | Purpose | Example |
+|-----------|---------|---------|
+| **Commands** | Entry points users invoke directly | `/work-issue 42` starts implementation workflow |
+| **Skills** | Domain knowledge modules | `issue-writing` knows how to structure good issues |
+| **Agents** | Autonomous subprocesses | `product-manager` combines skills for complex planning |
 
 ## Quick Start
 
+### Prerequisites
+
+- [Claude Code CLI](https://claude.ai/claude-code) installed
+- [Forgejo CLI](https://code.gitea.org/gitea/gitea-cli) (`tea`) for issue/PR management
+
 ### Installation
 
 ```bash
@@ -23,133 +58,126 @@ OpenCode uses three component types:
 git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
 cd architecture
 
-# Install symlinks to ~/.config/opencode/
+# Install symlinks to ~/.claude/
 make install
 ```
 
-This creates symlinks at:
-- `~/.config/opencode/skills/` → `.opencode/skills/`
-- `~/.config/opencode/tools/` → `.opencode/tools/`
-- `~/.config/opencode/agents/` → `.opencode/agents/`
-
-### Uninstallation
+### Forgejo Setup
 
 ```bash
-make uninstall
+# Install gitea-cli
+brew install gitea-cli
+
+# Authenticate (one-time)
+echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username
+
+# Required token scopes: read:user, read:repository, write:issue, write:repository
 ```
 
-### Status
+## Available Commands
 
-```bash
-make status
-```
-
-Shows current symlink state for each component.
-
-### Restart LLMs
-
-```bash
-make restart-llm
-```
-
-Restarts all local LLM services (atlas, forge, swift).
+| Command | Description |
+|---------|-------------|
+| `/dashboard` | Show open issues and PRs for the current repo |
+| `/work-issue <n>` | Fetch issue, create branch, implement, and create PR |
+| `/review-pr <n>` | Review a PR with diff analysis and feedback |
+| `/create-issue` | Create single or batch issues interactively |
+| `/plan-issues <desc>` | Break down a feature into discrete issues |
+| `/groom [n]` | Improve issue quality (single or batch) |
+| `/roadmap` | Visualize issues by status and dependencies |
 
 ## Project Structure
 
 ```
 architecture/
-├── legacy/                     # Historical Claude Code content
-│   ├── old/                    # Early Claude Code structure
-│   ├── old2/                   # Most recent Claude Code structure
-│   ├── docs/                   # Documentation
-│   ├── learnings/              # Governance learnings
-│   └── scripts/                # Bash scripts
-│
-├── .opencode/                  # OpenCode configuration
-│   ├── skills/                 # Reference knowledge (SKILL.md files)
-│   ├── tools/                  # Custom tools (TypeScript/JS)
-│   └── agents/                 # Specialized subagents (AGENT.md files)
-│
-├── Makefile                    # Symlink management
-├── settings.json               # Historical reference (Claude Code)
-└── README.md                   # This file
+├── manifesto.md        # Organization vision, personas, beliefs
+├── learnings/          # Captured learnings and governance
+├── commands/           # Slash commands invoked by users
+│   ├── work-issue.md
+│   ├── dashboard.md
+│   ├── review-pr.md
+│   ├── create-issue.md
+│   ├── plan-issues.md
+│   ├── groom.md
+│   └── roadmap.md
+├── skills/             # Reusable knowledge modules
+│   ├── gitea/        # Forgejo CLI integration
+│   ├── issue-writing/  # Issue structure best practices
+│   ├── backlog-grooming/  # Backlog maintenance
+│   ├── roadmap-planning/  # Feature breakdown
+│   └── code-review/    # Code review best practices
+├── agents/             # Specialized subagents
+│   ├── product-manager/  # Combines skills for PM tasks
+│   └── code-reviewer/  # Automated PR code review
+├── scripts/            # Git hooks and utilities
+│   └── pre-commit-checks.sh
+├── settings.json       # Claude Code configuration
+├── Makefile            # Symlink management
+└── CLAUDE.md           # Instructions for Claude Code
 ```
 
-## Adding Components
+## Example Workflows
 
-### Skills
+### Working on an Issue
 
-Create `.opencode/skills/<name>/SKILL.md`:
+```
+> /work-issue 42
 
-```markdown
----
-name: skill-name
-description: What this skill does and when to use it
----
-
-# Skill Title
-
-Content goes here...
+Fetching issue #42: "Add user authentication"
+Creating branch: feature/42-add-user-authentication
+Planning implementation...
+[Claude implements the feature]
+Creating PR with reference to issue...
 ```
 
-Skills are auto-discovered by OpenCode and available via the `skill` tool.
+### Planning a Feature
 
-### Tools
+```
+> /plan-issues Add dark mode support
 
-Create `.opencode/tools/<name>.ts`:
+Proposed Issues:
+1. Create theme context and provider
+2. Add theme toggle component
+3. Update components to use theme variables
+4. Add system preference detection
 
-```typescript
-import { tool } from "@opencode-ai/plugin"
-
-export default tool({
-  description: "What this tool does",
-  args: {
-    param: tool.schema.string().describe("Parameter description"),
-  },
-  async execute(args) {
-    // Your implementation
-    return "result"
-  },
-})
+Create these issues? [y/n]
 ```
 
-Tools are auto-discovered and available to the LLM.
+### Daily Standup
 
-### Agents
+```
+> /dashboard
 
-Create `.opencode/agents/<name>.md`:
+Open Issues (3):
+| #  | Title                    | Labels      |
+|----|--------------------------|-------------|
+| 42 | Add user authentication  | feature     |
+| 38 | Fix login redirect       | bug         |
+| 35 | Update dependencies      | maintenance |
 
-```markdown
----
-description: What this agent does and when to use it
-mode: subagent
-permission:
-  edit: deny
-  bash: deny
----
-
-You are an agent that specializes in...
+Open PRs (1):
+| #  | Title                    | Status      |
+|----|--------------------------|-------------|
+| 41 | Add password reset flow  | review      |
 ```
 
-Agents can be invoked with `@agent-name` or automatically by primary agents.
+## Configuration
 
-## Referencing Legacy Content
+The `settings.json` configures Claude Code behavior:
 
-The `legacy/` folder contains the original Claude Code structure for reference:
+- **Model selection**: Uses Opus for complex tasks
+- **Status line**: Shows git branch and status
+- **Hooks**: Pre-commit validation for secrets and YAML
 
-- **`legacy/old2/`** - Most recent Claude Code structure with skills, agents, commands
-- **`legacy/old2/manifesto.md`** - Organization vision and beliefs
-- **`legacy/old2/software-architecture.md`** - Architectural patterns and principles
-- **`legacy/old2/learnings/`** - Historical learnings (if any)
+## Uninstall
 
-These are preserved for historical reference but not actively used by OpenCode.
+```bash
+make uninstall
+```
 
-## Existing OpenCode Configuration
-
-Your global OpenCode configuration is at `~/.config/opencode/opencode.json`. This repository does not manage that file.
-
-The `settings.json` in this repository is kept for historical reference (it was used with Claude Code).
+This removes symlinks from `~/.claude/` and restores any backed-up files.
 
 ## License
 
-MIT
+MIT

VISION.md

@@ -0,0 +1,95 @@
+# 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:
+
+- Workflows vary between sessions and team members
+- Knowledge about good practices stays in heads, not systems
+- 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 Solution
+
+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.
+
+### Architecture
+
+Three component types 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 don't act on their own. Agents handle complex subtasks in isolation. Commands are the entry points that tie it together.
+
+## Product Principles
+
+These extend the organization's guiding principles:
+
+### Composability Over Complexity
+
+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 require user approval. Commands show what they're about to do and ask before doing it.
+
+*Extends: Non-goal "Replacing human judgment"*
+
+### 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. Complex workflows are available when needed, but not required to get value.
+
+*Extends: "Opinionated defaults, escape hatches available"*
+
+## Non-Goals
+
+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

@@ -0,0 +1,76 @@
+---
+name: code-reviewer
+description: Automated code review of pull requests. Reviews PRs for quality, bugs, security, style, and test coverage. Spawn after PR creation or for on-demand review.
+# Model: sonnet provides good code understanding for review tasks.
+# 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.
+
+## When Invoked
+
+You will receive a PR number to review. Follow this process:
+
+1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
+2. Analyze the diff for issues in these categories:
+   - **Code Quality**: Readability, maintainability, complexity
+   - **Bugs**: Logic errors, edge cases, null checks
+   - **Security**: Injection vulnerabilities, auth issues, data exposure
+   - **Style**: Naming conventions, formatting, consistency
+   - **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`
+6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
+
+## Review Comment Format
+
+Post reviews in this structured format:
+
+```markdown
+## AI Code Review
+
+> This is an automated review generated by the code-reviewer agent.
+
+### Summary
+[Brief overall assessment]
+
+### Findings
+
+#### Code Quality
+- [Finding 1]
+- [Finding 2]
+
+#### Potential Bugs
+- [Finding or "No issues found"]
+
+#### Security Concerns
+- [Finding or "No issues found"]
+
+#### Style Notes
+- [Finding or "Consistent with codebase"]
+
+#### Test Coverage
+- [Finding or "Adequate coverage"]
+
+### Verdict
+[LGTM / Needs Changes / Blocking Issues]
+```
+
+## Verdict Criteria
+
+- **LGTM**: No blocking issues, code meets quality standards, ready to merge
+- **Needs Changes**: Minor issues worth addressing before merge
+- **Blocking Issues**: Security vulnerabilities, logic errors, or missing critical functionality
+
+## Guidelines
+
+- Be specific: Reference exact lines and explain *why* something is an issue
+- Be constructive: Suggest alternatives when pointing out problems
+- Be kind: Distinguish between blocking issues and suggestions
+- Acknowledge good solutions when you see them

commands/create-issue.md

@@ -0,0 +1,43 @@
+---
+description: Create a new Gitea issue. Can create single issues or batch create from a plan.
+argument-hint: [title] or "batch"
+---
+
+# Create Issue(s)
+
+@~/.claude/skills/gitea/SKILL.md
+
+## Milestone Assignment
+
+Before creating issues, fetch available milestones:
+
+```bash
+tea milestones -f title,description
+```
+
+For each issue, automatically assign to the most relevant milestone by matching:
+- Issue content/problem area → Milestone title and description
+- If no clear match, ask the user which milestone (goal) the issue supports
+- If no milestones exist, skip milestone assignment
+
+Include `--milestone "<milestone>"` in the create command when a milestone is assigned.
+
+## Single Issue (default)
+
+If title provided:
+1. Create an issue with that title
+2. Ask for description
+3. Assign to appropriate milestone (see above)
+4. Ask if this issue depends on any existing issues
+5. If dependencies exist, link them: `tea issues deps add <new-issue> <blocker>`
+
+## Batch Mode
+
+If $1 is "batch":
+1. Ask user for the plan/direction
+2. Fetch available milestones
+3. Generate list of issues with titles, descriptions, milestone assignments, and dependencies
+4. Show for approval
+5. Create each issue with milestone (in dependency order)
+6. Link dependencies between created issues: `tea issues deps add <issue> <blocker>`
+7. Display all created issue numbers with dependency graph

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/dashboard.md

@@ -0,0 +1,13 @@
+---
+description: Show dashboard of open issues, PRs awaiting review, and CI status.
+---
+
+# Repository Dashboard
+
+@~/.claude/skills/gitea/SKILL.md
+
+Fetch and display:
+1. All open issues
+2. All open PRs
+
+Format as tables showing number, title, and author.

commands/groom.md

@@ -0,0 +1,37 @@
+---
+description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
+argument-hint: [issue-number]
+---
+
+# Groom Issues
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+
+## If issue number provided ($1):
+
+1. **Fetch the issue** details with `tea issues <number> --comments`
+2. **Check dependencies** with `tea issues deps list <number>`
+3. **Evaluate** against grooming checklist
+4. **Suggest improvements** for:
+   - Title clarity
+   - Description completeness
+   - Acceptance criteria quality
+   - Scope definition
+   - Missing or incorrect dependencies
+5. **Ask user** if they want to apply changes
+6. **Update issue** if approved
+7. **Link/unlink dependencies** if needed: `tea issues deps add/remove <issue> <dep>`
+
+## If no argument (groom all):
+
+1. **List open issues**
+2. **Review each** against grooming checklist (including dependencies)
+3. **Categorize**:
+   - Ready: Well-defined, dependencies linked, can start work
+   - Blocked: Has unresolved dependencies
+   - Needs work: Missing info, unclear, or missing dependency links
+   - Stale: No longer relevant
+4. **Present summary** table with dependency status
+5. **Offer to improve** issues that need work (including linking dependencies)

commands/improve.md

@@ -0,0 +1,84 @@
+---
+description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
+argument-hint:
+context: fork
+---
+
+# Improvement Analysis
+
+@~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+
+## Process
+
+1. **Read the vision**: Load `vision.md` from the repo root.
+   - If no vision exists, suggest running `/vision` first
+
+2. **Fetch current backlog**: Get all open issues from Gitea using `tea issues`
+
+3. **Analyze alignment**:
+
+   For each vision goal, check:
+   - Are there issues supporting this goal?
+   - Is there recent activity/progress?
+   - Are issues blocked or stalled?
+
+   For each open issue, check:
+   - Does it align with a vision goal?
+   - Is it supporting the current focus?
+
+4. **Identify gaps and opportunities**:
+
+   - **Unsupported goals**: Vision goals with no issues
+   - **Stalled goals**: Goals with issues but no recent progress
+   - **Orphan issues**: Issues that don't support any goal
+   - **Focus misalignment**: Issues not aligned with current focus getting priority
+   - **Missing non-goals**: Patterns suggesting things we should explicitly avoid
+
+5. **Present findings**:
+
+   ```
+   ## Vision Alignment Report
+
+   ### Goals Coverage
+   - Goal 1: [status] - N issues, [progress]
+   - Goal 2: [status] - N issues, [progress]
+
+   ### Gaps Identified
+   1. [Gap description]
+      Suggestion: [concrete action]
+
+   2. [Gap description]
+      Suggestion: [concrete action]
+
+   ### Orphan Issues
+   - #N: [title] - No goal alignment
+
+   ### Recommended Actions
+   1. [Action with rationale]
+   2. [Action with rationale]
+   ```
+
+6. **Offer to take action**:
+
+   For unsupported goals:
+   - Ask if user wants to plan issues for the gap
+   - If yes, run the `/plan-issues` workflow for that goal
+   - This breaks down the goal into concrete, actionable issues
+
+   For other findings:
+   - Re-prioritize issues based on focus
+   - Close or re-scope orphan issues
+   - Update vision with suggested changes
+
+   Always ask for approval before making changes.
+
+## Guidelines
+
+- Focus on actionable improvements, not just observations
+- Prioritize suggestions by impact on vision goals
+- Keep suggestions specific and concrete
+- One issue per improvement (don't bundle)
+- Reference specific goals when suggesting new issues

commands/manifesto.md

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

commands/plan-issues.md

@@ -0,0 +1,51 @@
+---
+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
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+@~/.claude/skills/vision-management/SKILL.md
+
+1. **Check vision context**: If `vision.md` exists, read it to understand personas, jobs to be done, and goals
+2. **Identify persona**: Which persona does "$1" serve?
+3. **Identify job**: Which job to be done does this enable?
+4. **Understand the feature**: Analyze what "$1" involves
+5. **Explore the codebase** if needed to understand context
+6. **Break down** into discrete, actionable issues:
+   - Each issue should be independently completable
+   - Clear dependencies between issues
+   - Appropriate scope (not too big, not too small)
+
+7. **Present the plan** (include vision alignment if vision exists):
+   ```
+   ## Proposed Issues for: $1
+
+   For: [Persona name]
+   Job: "[Job to be done this enables]"
+   Supports: [Milestone/Goal name]
+
+   1. [Title] - Brief description
+      Dependencies: none
+
+   2. [Title] - Brief description
+      Dependencies: #1
+
+   3. [Title] - Brief description
+      Dependencies: #1, #2
+   ```
+
+   If the feature doesn't align with any persona/job/goal, note this and ask if:
+   - A new persona or job should be added to the vision
+   - A new milestone should be created
+   - This should be added as a non-goal
+   - Proceed anyway (with justification)
+
+8. **Ask for approval** before creating issues
+9. **Create issues** in dependency order (blockers first)
+10. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
+11. **Present summary** with links to created issues and dependency graph

commands/retro.md

@@ -0,0 +1,116 @@
+---
+description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
+argument-hint: [task-description]
+---
+
+# Retrospective
+
+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.
+
+2. **Reflect on the work**: Ask the user (or summarize from conversation context if obvious):
+   - What friction points were encountered?
+   - What worked well?
+   - Any specific improvement ideas?
+
+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. **Create issue on architecture repo**: Always create issues on `flowmade-one/architecture`:
+
+   ```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]
+
+   ## Encoded In
+
+   - `skills/xxx/SKILL.md` - [what was added/changed]
+   - `commands/xxx.md` - [what was added/changed]
+
+   ## Governance
+
+   [What this means for how we work]
+   ```
+
+2. **Update skill/command/agent** with the encoded knowledge
+
+3. **Close the issue** with reference to the learning file and changes made
+
+## Encoding Destinations
+
+| Insight Type | Encode In |
+|--------------|-----------|
+| How to use a tool | `skills/[tool]/SKILL.md` |
+| Workflow improvement | `commands/[command].md` |
+| Subtask behavior | `agents/[agent]/agent.md` |
+| Organization belief | `manifesto.md` |
+| Product direction | `vision.md` (in product repo) |
+
+## Labels
+
+Add appropriate labels to issues:
+- `learning` - Always add this
+- `prompt-improvement` - For command/skill text changes
+- `new-feature` - For new commands/skills/agents
+- `bug` - For things that are broken
+
+## Guidelines
+
+- **Always create issues on architecture repo** - regardless of which repo the retro runs in
+- **Be specific**: Vague insights can't be encoded
+- **One issue per insight**: Don't bundle unrelated things
+- **Encoding happens later**: Retro captures the issue, encoding is separate work
+- **Skip one-offs**: Don't capture insights for edge cases that won't recur

commands/review-pr.md

@@ -0,0 +1,38 @@
+---
+description: Review a Gitea pull request. Fetches PR details, diff, and comments.
+argument-hint: <pr-number>
+---
+
+# Review PR #$1
+
+@~/.claude/skills/gitea/SKILL.md
+
+1. **View PR details** with `--comments` flag to see description, metadata, and discussion
+2. **Get the diff** to review the changes
+
+Review the changes and provide feedback on:
+- Code quality
+- Potential bugs
+- Test coverage
+- Documentation
+
+Ask the user what action to take:
+- **Merge**: Post review summary as comment, then merge with rebase style
+- **Request changes**: Leave feedback without merging
+- **Comment only**: Add a comment for discussion
+
+## Merging
+
+Always use tea CLI for merges to preserve user attribution:
+
+```bash
+tea pulls merge <number> --style rebase
+```
+
+For review comments, use `tea comment` since `tea pulls review` is interactive-only:
+
+```bash
+tea comment <number> "<review summary>"
+```
+
+> **Warning**: Never use the Gitea API with admin credentials for user-facing operations like merging. This causes the merge to be attributed to the admin account instead of the user.

commands/roadmap.md

@@ -0,0 +1,32 @@
+---
+description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
+argument-hint:
+---
+
+# Roadmap View
+
+@~/.claude/skills/gitea/SKILL.md
+
+1. **Fetch all open issues**
+2. **Analyze dependencies** from issue descriptions
+3. **Categorize issues**:
+   - Blocked: Waiting on other issues
+   - Ready: No blockers, can start
+   - In Progress: Has assignee or WIP label
+4. **Present roadmap** as organized list:
+
+```
+## Ready to Start
+- #5: Add user authentication
+- #8: Create dashboard layout
+
+## In Progress
+- #3: Setup database schema
+
+## Blocked
+- #7: User profile page (blocked by #5)
+- #9: Admin dashboard (blocked by #3, #8)
+```
+
+5. **Highlight** any issues that seem stale or unclear
+6. **Suggest** next actions based on the roadmap state

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

@@ -0,0 +1,209 @@
+---
+description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
+argument-hint: [goals]
+---
+
+# Product Vision
+
+@~/.claude/skills/vision-management/SKILL.md
+@~/.claude/skills/gitea/SKILL.md
+
+This command manages **product-level** vision. For organization-level vision, use `/manifesto`.
+
+## Architecture
+
+| Level | Document | Purpose | Command |
+|-------|----------|---------|---------|
+| **Organization** | `manifesto.md` | Who we are, shared personas, beliefs | `/manifesto` |
+| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` |
+| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` |
+
+Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
+
+## Manifesto Location
+
+The manifesto lives in the sibling `architecture` repo:
+
+```
+org/
+├── architecture/
+│   └── manifesto.md    ← organization manifesto
+├── product-a/
+│   └── vision.md       ← extends ../architecture/manifesto.md
+└── product-b/
+    └── vision.md
+```
+
+Look for manifesto in this order:
+1. `./manifesto.md` (if this IS the architecture repo)
+2. `../architecture/manifesto.md` (sibling repo)
+
+## Process
+
+1. **Load organization context**: Find and read `manifesto.md` using the location rules above
+   - Extract personas (Who We Serve)
+   - Extract jobs to be done (What They're Trying to Achieve)
+   - Extract guiding principles
+   - Extract non-goals
+   - If not found, warn and continue without inheritance context
+
+2. **Check for product vision**: Look for `vision.md` in the current repo root
+
+3. **If no vision exists**:
+   - Show the organization manifesto summary
+   - Ask if the user wants to create a product vision
+   - Guide them through defining (with inheritance):
+
+     **Who This Product Serves**
+     - Show manifesto personas first
+     - Ask: "Which personas does this product serve? How does it extend or specialize them?"
+     - Product personas should reference org personas with product-specific context
+
+     **What They're Trying to Achieve**
+     - Show manifesto jobs first
+     - Ask: "What product-specific jobs does this enable? How do they trace back to org jobs?"
+     - Use a table format showing the connection
+
+     **The Problem**
+     - What pain points does this product solve?
+
+     **The Solution**
+     - How does this product address those jobs?
+
+     **Product Principles**
+     - Show manifesto principles first
+     - Ask: "Any product-specific principles? These should extend, not duplicate."
+     - Each principle should note what org principle it extends
+
+     **Product Non-Goals**
+     - Show manifesto non-goals first
+     - Ask: "Any product-specific non-goals?"
+     - Org non-goals apply automatically
+
+   - Create `vision.md` with proper inheritance markers
+   - Ask about initial goals, create as Gitea milestones
+
+4. **If vision exists**:
+   - Display organization context summary
+   - Display the product vision from `vision.md`
+   - Validate inheritance (warn if vision duplicates rather than extends)
+   - Show current milestones and their progress: `tea milestones`
+   - Check if `$1` specifies an action:
+     - `goals`: Manage milestones (add, close, view progress)
+   - If no action specified, just display the current state
+
+5. **Managing Goals (milestones)**:
+   ```bash
+   # List milestones with progress
+   tea milestones
+
+   # Create a new goal
+   tea milestones create --title "<goal>" --description "For: <persona>
+Job: <job to be done>
+Success: <criteria>"
+
+   # View issues in a milestone
+   tea milestones issues <milestone-name>
+
+   # Close a completed goal
+   tea milestones close <milestone-name>
+   ```
+
+## Vision Structure Template
+
+```markdown
+# Vision
+
+This product vision builds on the [organization manifesto](../architecture/manifesto.md).
+
+## Who This Product Serves
+
+### [Persona Name]
+
+[Product-specific description]
+
+*Extends: [Org persona] (from manifesto)*
+
+## What They're Trying to Achieve
+
+These trace back to organization-level jobs:
+
+| Product Job | Enables Org Job |
+|-------------|-----------------|
+| "[Product-specific job]" | "[Org job from manifesto]" |
+
+## The Problem
+
+[Pain points this product addresses]
+
+## The Solution
+
+[How this product solves those problems]
+
+## Product Principles
+
+These extend the organization's guiding principles:
+
+### [Principle Name]
+
+[Description]
+
+*Extends: "[Org principle]"*
+
+## Non-Goals
+
+These extend the organization's non-goals:
+
+- **[Non-goal].** [Explanation]
+```
+
+## Output Format
+
+```
+## Organization Context
+
+From manifesto.md:
+- **Personas**: [list from manifesto]
+- **Core beliefs**: [key beliefs]
+- **Principles**: [list]
+
+## Product: [Name]
+
+### Who This Product Serves
+
+- **[Persona 1]**: [Product-specific description]
+  ↳ Extends: [Org persona]
+
+### What They're Trying to Achieve
+
+| Product Job | → Org Job |
+|-------------|-----------|
+| [job] | [org job it enables] |
+
+### Vision Summary
+
+[Problem/solution from vision.md]
+
+### Goals (Milestones)
+
+| Goal | For | Progress | Due |
+|------|-----|----------|-----|
+| [title] | [Persona] | 3/5 issues | [date] |
+```
+
+## Inheritance Rules
+
+- **Personas**: Product personas extend org personas with product-specific context
+- **Jobs**: Product jobs trace back to org-level jobs (show the connection)
+- **Beliefs**: Inherited from manifesto, never duplicated in vision
+- **Principles**: Product adds specific principles that extend org principles
+- **Non-Goals**: Product adds its own; org non-goals apply automatically
+
+## Guidelines
+
+- Product vision builds on organization manifesto - extend, don't duplicate
+- Every product persona should reference which org persona it extends
+- Every product job should show which org job it enables
+- Product principles should note which org principle they extend
+- Use `/manifesto` for organization-level identity and beliefs
+- Use `/vision` for product-specific direction and goals

commands/work-issue.md

@@ -0,0 +1,17 @@
+---
+description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
+argument-hint: <issue-number>
+---
+
+# Work on Issue #$1
+
+@~/.claude/skills/gitea/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
+5. **Commit** with message referencing the issue
+6. **Push** the branch to origin
+7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
+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

docs/writing-agents.md

@@ -0,0 +1,709 @@
+# Writing Agents
+
+A guide to creating specialized subagents that combine multiple skills for complex, context-isolated tasks.
+
+## What is an Agent?
+
+Agents are **specialized subprocesses** that combine multiple skills into focused personas. Unlike commands (which define workflows) or skills (which encode knowledge), agents are autonomous workers that can handle complex tasks independently.
+
+Think of agents as specialists you can delegate work to. They have their own context, their own expertise (via skills), and they report back when finished.
+
+## File Structure
+
+Agents live in the `agents/` directory, each in its own folder:
+
+```
+agents/
+└── product-manager/
+    └── AGENT.md
+```
+
+### Why AGENT.md?
+
+The uppercase `AGENT.md` filename:
+- Makes the agent file immediately visible in directory listings
+- Follows a consistent convention across all agents
+- Clearly identifies the primary file in an agent folder
+
+### Supporting Files (Optional)
+
+An agent folder can contain additional files if needed:
+
+```
+agents/
+└── code-reviewer/
+    ├── AGENT.md           # Main agent document (required)
+    └── checklists/        # Supporting materials
+        └── security.md
+```
+
+However, prefer keeping everything in `AGENT.md` when possible—agent definitions should be concise.
+
+## Agent Document Structure
+
+A well-structured `AGENT.md` follows this pattern:
+
+```markdown
+# Agent Name
+
+Brief description of what this agent does.
+
+## Skills
+List of skills this agent has access to.
+
+## Capabilities
+What the agent can do—its areas of competence.
+
+## When to Use
+Guidance on when to spawn this agent.
+
+## Behavior
+How the agent should operate—rules and constraints.
+```
+
+All sections are important:
+- **Skills**: Defines what knowledge the agent has
+- **Capabilities**: Tells spawners what to expect
+- **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.
+
+### Skill Composition
+
+```
+┌────────────────────────────────────────────────┐
+│           Product Manager Agent                │
+│                                                │
+│  ┌──────────┐  ┌──────────────┐                │
+│  │ gitea  │  │issue-writing │                │
+│  │          │  │              │                │
+│  │ CLI      │  │ Structure    │                │
+│  │ commands │  │ patterns     │                │
+│  └──────────┘  └──────────────┘                │
+│                                                │
+│  ┌──────────────────┐  ┌─────────────────┐     │
+│  │backlog-grooming  │  │roadmap-planning │     │
+│  │                  │  │                 │     │
+│  │ Review           │  │ Feature         │     │
+│  │ checklists       │  │ breakdown       │     │
+│  └──────────────────┘  └─────────────────┘     │
+│                                                │
+└────────────────────────────────────────────────┘
+```
+
+The agent can:
+- Use **gitea** to interact with issues and PRs
+- Apply **issue-writing** patterns when creating content
+- Follow **backlog-grooming** checklists when reviewing
+- Use **roadmap-planning** strategies when breaking down features
+
+### Emergent Capabilities
+
+When skills combine, new capabilities emerge:
+
+| Skills Combined | Emergent Capability |
+|-----------------|---------------------|
+| gitea + issue-writing | Create well-structured issues programmatically |
+| backlog-grooming + issue-writing | Improve existing issues systematically |
+| roadmap-planning + gitea | Plan and create linked issue hierarchies |
+| All four skills | Full backlog management lifecycle |
+
+## Use Cases for Agents
+
+### 1. Parallel Processing
+
+Agents work independently with their own context. Spawn multiple agents to work on separate tasks simultaneously.
+
+```
+Command: /groom (batch mode)
+         │
+         ├─── Spawn Agent: Review issues #1-5
+         │
+         ├─── Spawn Agent: Review issues #6-10
+         │
+         └─── Spawn Agent: Review issues #11-15
+
+         ↓ (agents work in parallel)
+
+Results aggregated by command
+```
+
+**Use when:**
+- Tasks are independent and don't need to share state
+- Workload can be divided into discrete chunks
+- Speed matters more than sequential consistency
+
+### 2. Context Isolation
+
+Each agent maintains separate conversation state. This prevents context pollution when handling complex, unrelated subtasks.
+
+```
+Main Context                    Agent Context
+┌─────────────────┐            ┌─────────────────┐
+│ User working on │            │ Isolated work   │
+│ feature X       │   spawn    │ on backlog      │
+│                 │ ─────────► │ review          │
+│ (preserves      │            │                 │
+│  feature X      │   return   │ (doesn't know   │
+│  context)       │ ◄───────── │  about X)       │
+└─────────────────┘            └─────────────────┘
+```
+
+**Use when:**
+- Subtask requires deep exploration that would pollute main context
+- Work involves many files or concepts unrelated to main task
+- You want clean separation between different concerns
+
+### 3. Complex Workflows
+
+Some workflows are better handled by a specialized agent than by inline execution. Agents can make decisions, iterate, and adapt.
+
+```
+Command: /plan-issues "add user authentication"
+         │
+         └─── Spawn product-manager agent
+                   │
+                   ├── Explore codebase to understand structure
+                   ├── Research authentication patterns
+                   ├── Design issue breakdown
+                   ├── Create issues in dependency order
+                   └── Return summary to command
+```
+
+**Use when:**
+- Task requires iterative decision-making
+- Workflow has many steps that depend on intermediate results
+- Specialist expertise (via combined skills) adds value
+
+### 4. Autonomous Exploration
+
+Agents can explore codebases independently, building understanding without polluting the main conversation.
+
+**Use when:**
+- You need to understand a new part of the codebase
+- 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:
+
+- **Simple, single-skill task**: Writing one issue doesn't need an agent
+- **Main context is relevant**: The current conversation context helps
+- **Quick reference needed**: Just need to check a pattern or command
+- **Sequential workflow**: Command can orchestrate step-by-step
+
+Example: Creating a single issue with `/create-issue`
+```
+Command reads issue-writing skill directly
+         │
+         └── Creates one issue following patterns
+```
+
+### Use an Agent When:
+
+- **Multiple skills needed together**: Complex tasks benefit from composition
+- **Context isolation required**: Don't want to pollute main conversation
+- **Parallel execution possible**: Can divide and conquer
+- **Autonomous exploration needed**: Agent can figure things out independently
+- **Specialist persona helps**: "Product manager" framing improves outputs
+
+Example: Grooming entire backlog with `/groom`
+```
+Command spawns product-manager agent
+         │
+         └── Agent iterates through all issues
+             using multiple skills
+```
+
+### Decision Matrix
+
+| Scenario | Agent? | Reason |
+|----------|--------|--------|
+| Create one issue | No | Single skill, simple task |
+| Review 20 issues | Yes | Batch processing, isolation |
+| Quick CLI lookup | No | Just need gitea reference |
+| Plan new feature | Yes | Multiple skills, exploration |
+| Fix issue title | No | Trivial edit |
+| Reorganize backlog | Yes | Complex, multi-skill workflow |
+
+## Annotated Example: Product Manager Agent
+
+Let's examine the `product-manager` agent in detail:
+
+```markdown
+# Product Manager Agent
+
+Specialized agent for backlog management and roadmap planning.
+```
+
+**The opening** identifies the agent's role clearly. "Product Manager" is a recognizable persona that sets expectations.
+
+```markdown
+## Skills
+
+- gitea
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+```
+
+**Skills section** lists all knowledge the agent has access to. These skills are loaded into the agent's context when spawned. The combination enables:
+- Reading/writing issues (gitea)
+- Creating quality content (issue-writing)
+- Evaluating existing issues (backlog-grooming)
+- Planning work strategically (roadmap-planning)
+
+```markdown
+## Capabilities
+
+This agent can:
+- Review and improve existing issues
+- Create new well-structured issues
+- Analyze the backlog for gaps and priorities
+- Plan feature breakdowns
+- Maintain roadmap clarity
+```
+
+**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
+- "Review and improve" = backlog-grooming + issue-writing
+- "Create new issues" = gitea + issue-writing
+- "Analyze backlog" = backlog-grooming + roadmap-planning
+- "Plan breakdowns" = roadmap-planning + issue-writing
+
+```markdown
+## When to Use
+
+Spawn this agent for:
+- Batch operations on multiple issues
+- Comprehensive backlog reviews
+- Feature planning that requires codebase exploration
+- Complex issue creation with dependencies
+```
+
+**When to Use section** guides appropriate usage. Note the criteria:
+- "Batch operations" → Parallel/isolation benefit
+- "Comprehensive reviews" → Complex workflow benefit
+- "Requires exploration" → Context isolation benefit
+- "Complex with dependencies" → Multi-skill benefit
+
+```markdown
+## Behavior
+
+- Always fetches current issue state before making changes
+- Asks for approval before creating or modifying issues
+- Provides clear summaries of actions taken
+- Uses the tea CLI for all Forgejo operations
+```
+
+**Behavior section** sets operational rules. These ensure:
+- Accuracy: Fetches current state, doesn't assume
+- Safety: Asks before acting
+- Transparency: Summarizes what happened
+- Consistency: Uses standard tooling
+
+## Naming Conventions
+
+### Agent Folder Names
+
+- Use **kebab-case**: `product-manager`, `code-reviewer`
+- Name by **role or persona**: what the agent "is"
+- Keep **recognizable**: familiar roles are easier to understand
+
+Good names:
+- `product-manager` - Recognizable role
+- `code-reviewer` - Clear function
+- `security-auditor` - Specific expertise
+- `documentation-writer` - Focused purpose
+
+Avoid:
+- `helper` - Too vague
+- `do-stuff` - Not a role
+- `issue-thing` - Not recognizable
+
+### Agent Titles
+
+The H1 title in `AGENT.md` should be the role name in Title Case:
+
+| Folder | Title |
+|--------|-------|
+| `product-manager` | Product Manager Agent |
+| `code-reviewer` | Code Reviewer Agent |
+| `security-auditor` | Security Auditor Agent |
+
+## Model Selection
+
+Agents can specify which Claude model to use via the `model` field in YAML frontmatter. Choosing the right model balances capability, speed, and cost.
+
+### Available Models
+
+| Model | Characteristics | Best For |
+|-------|-----------------|----------|
+| `haiku` | Fastest, most cost-effective | Simple structured tasks, formatting, basic transformations |
+| `sonnet` | Balanced speed and capability | Most agent tasks, code review, issue management |
+| `opus` | Most capable, best reasoning | Complex analysis, architectural decisions, nuanced judgment |
+| `inherit` | Uses parent context's model | When agent should match caller's capability level |
+
+### Decision Matrix
+
+| Agent Task Type | Recommended Model | Reasoning |
+|-----------------|-------------------|-----------|
+| Structured output formatting | `haiku` | Pattern-following, no complex reasoning |
+| Code review (style/conventions) | `sonnet` | Needs code understanding, not deep analysis |
+| Security vulnerability analysis | `opus` | Requires nuanced judgment, high stakes |
+| Issue triage and labeling | `haiku` or `sonnet` | Mostly classification tasks |
+| Feature planning and breakdown | `sonnet` or `opus` | Needs strategic thinking |
+| Batch processing (many items) | `haiku` or `sonnet` | Speed and cost matter at scale |
+| Architectural exploration | `opus` | Complex reasoning about tradeoffs |
+
+### Examples
+
+These examples show recommended model configurations for different agent types:
+
+**Code Reviewer Agent** - Use `sonnet`:
+```yaml
+---
+name: code-reviewer
+model: sonnet
+skills: gitea, code-review
+---
+```
+Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.
+
+**Security Auditor Agent** (hypothetical) - Use `opus`:
+```yaml
+---
+name: security-auditor
+model: opus
+skills: code-review  # would add security-specific skills
+---
+```
+Security analysis requires careful, nuanced judgment where missing issues have real consequences. Worth the extra capability.
+
+**Formatting Agent** (hypothetical) - Use `haiku`:
+```yaml
+---
+name: markdown-formatter
+model: haiku
+skills: documentation
+---
+```
+Pure formatting tasks follow patterns and don't require complex reasoning. Haiku is fast and sufficient.
+
+### Best Practices for Model Selection
+
+1. **Start with `sonnet`** - It handles most agent tasks well
+2. **Use `haiku` for volume** - When processing many items, speed and cost add up
+3. **Reserve `opus` for judgment** - Use when errors are costly or reasoning is complex
+4. **Avoid `inherit` by default** - Make a deliberate choice; `inherit` obscures the decision
+5. **Consider the stakes** - Higher consequence tasks warrant more capable models
+6. **Test with real tasks** - Verify the chosen model performs adequately
+
+### When to Use `inherit`
+
+The `inherit` option has legitimate uses:
+
+- **Utility agents**: Small helpers that should match their caller's capability
+- **Delegation chains**: When an agent spawns sub-agents that should stay consistent
+- **Testing/development**: When you want to control model from the top level
+
+However, most production agents should specify an explicit model.
+
+## Best Practices
+
+### 1. Choose Skills Deliberately
+
+Include only skills the agent needs. More skills = more context = potential confusion.
+
+**Too many skills:**
+```markdown
+## Skills
+- gitea
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+- code-review
+- testing
+- documentation
+- deployment
+```
+
+**Right-sized:**
+```markdown
+## Skills
+- gitea
+- issue-writing
+- backlog-grooming
+- roadmap-planning
+```
+
+### 2. Define Clear Boundaries
+
+Agents should know what they can and cannot do.
+
+**Vague:**
+```markdown
+## Capabilities
+This agent can help with project management.
+```
+
+**Clear:**
+```markdown
+## Capabilities
+This agent can:
+- Review and improve existing issues
+- Create new well-structured issues
+- Analyze the backlog for gaps
+
+This agent cannot:
+- Merge pull requests
+- Deploy code
+- Make architectural decisions
+```
+
+### 3. Set Behavioral Guardrails
+
+Prevent agents from causing problems by setting explicit rules.
+
+**Important behaviors to specify:**
+- When to ask for approval
+- What to do before making changes
+- How to report results
+- Error handling expectations
+
+### 4. Match Persona to Purpose
+
+The agent's name and description should align with its skills and capabilities.
+
+**Mismatched:**
+```markdown
+# Security Agent
+
+## Skills
+- issue-writing
+- documentation
+```
+
+**Aligned:**
+```markdown
+# Security Auditor Agent
+
+## Skills
+- security-scanning
+- vulnerability-assessment
+- code-review
+```
+
+### 5. Keep Agents Focused
+
+One agent = one role. If an agent does too many unrelated things, split it.
+
+**Too broad:**
+```markdown
+# Everything Agent
+Handles issues, code review, deployment, and customer support.
+```
+
+**Focused:**
+```markdown
+# Product Manager Agent
+Specialized for backlog management and roadmap planning.
+```
+
+## When to Create a New Agent
+
+Create an agent when you need:
+
+1. **Role-based expertise**: A recognizable persona improves outputs
+2. **Skill composition**: Multiple skills work better together
+3. **Context isolation**: Work shouldn't pollute main conversation
+4. **Parallel capability**: Tasks can run independently
+5. **Autonomous operation**: Agent should figure things out on its own
+
+### Signs You Need a New Agent
+
+- Commands repeatedly spawn similar skill combinations
+- Tasks require deep exploration that pollutes context
+- Work benefits from a specialist "persona"
+- Batch processing would help
+
+### Signs You Don't Need a New Agent
+
+- Single skill is sufficient
+- Task is simple and sequential
+- Main context is helpful, not harmful
+- No clear persona or role emerges
+
+## Agent Lifecycle
+
+### 1. Design
+
+Define the agent's role:
+- What persona makes sense?
+- Which skills does it need?
+- What can it do (and not do)?
+- When should it be spawned?
+
+### 2. Implement
+
+Create the agent file:
+- Clear name and description
+- Appropriate skill list
+- Specific capabilities
+- Usage guidance
+- Behavioral rules
+
+### 3. Integrate
+
+Connect the agent to workflows:
+- Update commands that should spawn it
+- Document in ARCHITECTURE.md
+- Test with real tasks
+
+### 4. Refine
+
+Improve based on usage:
+- Add/remove skills as needed
+- Clarify capabilities
+- Strengthen behavioral rules
+- Update documentation
+
+## 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
+
+### 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
+
+## See Also
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md): How agents fit into the overall system
+- [writing-skills.md](writing-skills.md): Creating the skills that agents use
+- [VISION.md](../VISION.md): The philosophy behind composable components

docs/writing-commands.md

@@ -0,0 +1,731 @@
+# Writing Commands
+
+A guide to creating user-facing entry points that trigger workflows.
+
+## What is a Command?
+
+Commands are **user-facing entry points** that trigger workflows. Unlike skills (which encode knowledge) or agents (which execute tasks autonomously), commands define *what* to do—they orchestrate the workflow that users invoke directly.
+
+Think of commands as the interface between users and the system. Users type `/work-issue 42` and the command defines the entire workflow: fetch issue, create branch, implement, commit, push, create PR.
+
+## File Structure
+
+Commands live directly in the `commands/` directory as markdown files:
+
+```
+commands/
+├── work-issue.md
+├── dashboard.md
+├── review-pr.md
+├── create-issue.md
+├── groom.md
+├── roadmap.md
+└── plan-issues.md
+```
+
+### Why Flat Files?
+
+Unlike skills and agents (which use folders), commands are single files because:
+- Commands are self-contained workflow definitions
+- No supporting files needed
+- Simple naming: `/work-issue` maps to `work-issue.md`
+
+## Command Document Structure
+
+A well-structured command file has two parts:
+
+### 1. Frontmatter (YAML Header)
+
+```yaml
+---
+description: Brief description shown in command listings
+argument-hint: <required-arg> [optional-arg]
+---
+```
+
+#### Required Fields
+
+| Field | Purpose |
+|-------|---------|
+| `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)
+
+```markdown
+# Command Title
+
+Brief intro if needed.
+
+1. **Step one**: What to do
+2. **Step two**: What to do next
+...
+```
+
+The body contains the workflow steps that Claude follows when the command is invoked.
+
+## Complete Command Example
+
+```markdown
+---
+description: Work on a Gitea issue. Fetches issue details and sets up branch.
+argument-hint: <issue-number>
+---
+
+# Work on Issue #$1
+
+@~/.claude/skills/gitea/SKILL.md
+
+1. **View the issue** to understand requirements
+2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
+3. **Plan**: Use TodoWrite to break down the work
+4. **Implement** the changes
+5. **Commit** with message referencing the issue
+6. **Push** the branch to origin
+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.
+
+### The ARGUMENTS Pattern
+
+When users invoke a command with arguments:
+```
+/work-issue 42
+```
+
+The system provides the arguments via the `$1`, `$2`, etc. placeholders in the command body:
+```markdown
+# Work on Issue #$1
+1. **View the issue** to understand requirements
+```
+
+Becomes:
+```markdown
+# Work on Issue #42
+1. **View the issue** to understand requirements
+```
+
+### Argument Hints
+
+Use `argument-hint` in frontmatter to document expected arguments:
+
+| Pattern | Meaning |
+|---------|---------|
+| `<arg>` | Required argument |
+| `[arg]` | Optional argument |
+| `<arg1> <arg2>` | Multiple required |
+| `[arg1] [arg2]` | Multiple optional |
+| `<required> [optional]` | Mix of both |
+
+Examples:
+```yaml
+argument-hint: <issue-number>           # One required
+argument-hint: [issue-number]           # One optional
+argument-hint: <title> [description]    # Required + optional
+argument-hint: [title] or "batch"       # Choice of modes
+```
+
+### Handling Optional Arguments
+
+Commands often have different behavior based on whether arguments are provided:
+
+```markdown
+---
+description: Groom issues. Without argument, reviews all. With argument, grooms specific issue.
+argument-hint: [issue-number]
+---
+
+# Groom Issues
+
+@~/.claude/skills/gitea/SKILL.md
+
+## If issue number provided ($1):
+1. **Fetch the issue** details
+2. **Evaluate** against checklist
+...
+
+## If no argument (groom all):
+1. **List open issues**
+2. **Review each** against checklist
+...
+```
+
+### Multiple Modes
+
+Some commands support distinct modes based on the first argument:
+
+```markdown
+---
+description: Create issues. Single or batch mode.
+argument-hint: [title] or "batch"
+---
+
+# Create Issue(s)
+
+@~/.claude/skills/gitea/SKILL.md
+
+## Single Issue (default)
+If title provided, create an issue with that title.
+
+## Batch Mode
+If $1 is "batch":
+1. Ask user for the plan
+2. Generate list of issues
+3. Show for approval
+4. Create each issue
+```
+
+## Including Skills
+
+Commands include skills using the `@` file reference syntax. This automatically injects the skill content into the command context when the command is invoked.
+
+### File Reference Syntax
+
+Use the `@` prefix followed by the path to the skill file:
+
+```markdown
+# Groom Issues
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+
+1. **Fetch the issue** details
+2. **Evaluate** against grooming checklist
+...
+```
+
+When the command runs, the content of each referenced skill file is automatically loaded into context.
+
+### Why File References?
+
+**DO NOT** use phrases like "Use the gitea skill" - skills have only ~20% auto-activation rate. File references guarantee the skill content is available.
+
+| Pattern | Behavior |
+|---------|----------|
+| `@~/.claude/skills/gitea/SKILL.md` | Content automatically injected |
+| "Use the gitea skill" | Relies on auto-activation (~20% success) |
+
+### When to Include Skills
+
+| Include explicitly | Skip skill reference |
+|-------------------|---------------------|
+| CLI syntax is needed | Well-known commands |
+| Core methodology required | Simple operations |
+| Quality standards matter | One-off actions |
+| Patterns should be followed | No domain knowledge needed |
+
+## Invoking Agents
+
+Commands can spawn agents for complex subtasks that benefit from skill composition or context isolation.
+
+### Spawning Agents
+
+```markdown
+For comprehensive backlog review, spawn the **product-manager** agent to:
+- Review all open issues
+- Categorize by readiness
+- Propose improvements
+```
+
+### When to Spawn Agents
+
+Spawn an agent when the command needs:
+- **Parallel processing**: Multiple independent tasks
+- **Context isolation**: Deep exploration that would pollute main context
+- **Skill composition**: Multiple skills working together
+- **Autonomous operation**: Let the agent figure out details
+
+### Example: Conditional Agent Spawning
+
+```markdown
+# Groom Issues
+
+## If no argument (groom all):
+For large backlogs (>10 issues), consider spawning the
+product-manager agent to handle the review autonomously.
+```
+
+## Interactive Patterns
+
+Commands often require user interaction for confirmation, choices, or input.
+
+### Approval Workflows
+
+Always ask for approval before significant actions:
+
+```markdown
+5. **Ask for approval** before creating issues
+6. **Create issues** in order
+```
+
+Common approval points:
+- Before creating/modifying resources (issues, PRs, files)
+- Before executing destructive operations
+- When presenting a plan that will be executed
+
+### Presenting Choices
+
+When the command leads to multiple possible actions:
+
+```markdown
+Ask the user what action to take:
+- **Merge**: Approve and merge the PR
+- **Request changes**: Leave feedback without merging
+- **Comment only**: Add a comment for discussion
+```
+
+### Gathering Input
+
+Some commands need to gather information from the user:
+
+```markdown
+## Batch Mode
+If $1 is "batch":
+1. **Ask user** for the plan/direction
+2. Generate list of issues with titles and descriptions
+3. Show for approval
+```
+
+### Presenting Results
+
+Commands should clearly show what was done:
+
+```markdown
+7. **Update dependencies** with actual issue numbers after creation
+8. **Present summary** with links to created issues
+```
+
+Good result presentations include:
+- Tables for lists of items
+- Links for created resources
+- Summaries of changes made
+- Next step suggestions
+
+## Annotated Examples
+
+Let's examine existing commands to understand effective patterns.
+
+### Example 1: work-issue (Linear Workflow)
+
+```markdown
+---
+description: Work on a Gitea issue. Fetches issue details and sets up branch.
+argument-hint: <issue-number>
+---
+
+# Work on Issue #$1
+
+@~/.claude/skills/gitea/SKILL.md
+
+1. **View the issue** to understand requirements
+2. **Create a branch**: `git checkout -b issue-$1-<short-kebab-title>`
+3. **Plan**: Use TodoWrite to break down the work
+4. **Implement** the changes
+5. **Commit** with message referencing the issue
+6. **Push** the branch to origin
+7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
+```
+
+**Key patterns:**
+- **Linear workflow**: Clear numbered steps in order
+- **Required argument**: `<issue-number>` means must provide
+- **Variable substitution**: `$1` used throughout
+- **Skill reference**: Uses gitea skill for CLI knowledge
+- **Git integration**: Branch and push steps specified
+
+### Example 2: dashboard (No Arguments)
+
+```markdown
+---
+description: Show dashboard of open issues, PRs awaiting review, and CI status.
+---
+
+# Repository Dashboard
+
+@~/.claude/skills/gitea/SKILL.md
+
+Fetch and display:
+1. All open issues
+2. All open PRs
+
+Format as tables showing issue/PR number, title, and author.
+```
+
+**Key patterns:**
+- **No argument-hint**: Command takes no arguments
+- **Output formatting**: Specifies how to present results
+- **Aggregation**: Combines multiple data sources
+- **Simple workflow**: Just fetch and display
+
+### Example 3: groom (Optional Argument with Modes)
+
+```markdown
+---
+description: Groom and improve issues. Without argument, reviews all. With argument, grooms specific issue.
+argument-hint: [issue-number]
+---
+
+# Groom Issues
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/backlog-grooming/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+
+## If issue number provided ($1):
+1. **Fetch the issue** details
+2. **Evaluate** against grooming checklist
+3. **Suggest improvements** for:
+   - Title clarity
+   - Description completeness
+   - Acceptance criteria quality
+4. **Ask user** if they want to apply changes
+5. **Update issue** if approved
+
+## If no argument (groom all):
+1. **List open issues**
+2. **Review each** against grooming checklist
+3. **Categorize**: Ready / Needs work / Stale
+4. **Present summary** table
+5. **Offer to improve** issues that need work
+```
+
+**Key patterns:**
+- **Optional argument**: `[issue-number]` with brackets
+- **Mode switching**: Different behavior based on argument presence
+- **Skill file references**: Uses `@~/.claude/skills/` to include multiple skills
+- **Approval workflow**: "Ask user if they want to apply changes"
+- **Categorization**: Groups items for presentation
+
+### Example 4: plan-issues (Complex Workflow)
+
+```markdown
+---
+description: Plan and create issues for a feature. Breaks down work into well-structured issues.
+argument-hint: <feature-description>
+---
+
+# Plan Feature: $1
+
+@~/.claude/skills/gitea/SKILL.md
+@~/.claude/skills/roadmap-planning/SKILL.md
+@~/.claude/skills/issue-writing/SKILL.md
+
+1. **Understand the feature**: Analyze what "$1" involves
+2. **Explore the codebase** if needed to understand context
+3. **Break down** into discrete, actionable issues
+4. **Present the plan**:
+   ```
+   ## Proposed Issues for: $1
+
+   1. [Title] - Brief description
+      Dependencies: none
+   ...
+   ```
+5. **Ask for approval** before creating issues
+6. **Create issues** in order
+7. **Update dependencies** with actual issue numbers
+8. **Present summary** with links to created issues
+```
+
+**Key patterns:**
+- **Multi-skill composition**: Includes three skills via `@~/.claude/skills/`
+- **Codebase exploration**: May need to understand context
+- **Structured output**: Template for presenting the plan
+- **Two-phase execution**: Plan first, then execute after approval
+- **Dependency management**: Creates issues in order, updates references
+
+### Example 5: review-pr (Action Choices)
+
+```markdown
+---
+description: Review a Gitea pull request. Fetches PR details, diff, and comments.
+argument-hint: <pr-number>
+---
+
+# Review PR #$1
+
+@~/.claude/skills/gitea/SKILL.md
+
+1. **View PR details** including description and metadata
+2. **Get the diff** to review the changes
+
+Review the changes and provide feedback on:
+- Code quality
+- Potential bugs
+- Test coverage
+- Documentation
+
+Ask the user what action to take:
+- **Merge**: Approve and merge the PR
+- **Request changes**: Leave feedback without merging
+- **Comment only**: Add a comment for discussion
+```
+
+**Key patterns:**
+- **Information gathering**: Fetches context before analysis
+- **Review criteria**: Checklist of what to examine
+- **Action menu**: Clear choices with explanations
+- **User decides outcome**: Command presents options, user chooses
+
+## Naming Conventions
+
+### Command File Names
+
+- Use **kebab-case**: `work-issue.md`, `plan-issues.md`
+- Use **verbs or verb phrases**: Commands are actions
+- Be **concise**: 1-3 words is ideal
+- Match the **invocation**: `/work-issue` → `work-issue.md`
+
+Good names:
+- `work-issue` - Action + target
+- `dashboard` - What it shows
+- `review-pr` - Action + target
+- `plan-issues` - Action + target
+- `groom` - Action (target implied)
+
+Avoid:
+- `issue-work` - Noun-first is awkward
+- `do-stuff` - Too vague
+- `manage-issues-and-prs` - Too long
+
+### Command Titles
+
+The H1 title can be more descriptive than the filename:
+
+| Filename | Title |
+|----------|-------|
+| `work-issue.md` | Work on Issue #$1 |
+| `dashboard.md` | Repository Dashboard |
+| `plan-issues.md` | Plan Feature: $1 |
+
+## Best Practices
+
+### 1. Design Clear Workflows
+
+Each step should be unambiguous:
+
+**Vague:**
+```markdown
+1. Handle the issue
+2. Do the work
+3. Finish up
+```
+
+**Clear:**
+```markdown
+1. **View the issue** to understand requirements
+2. **Create a branch**: `git checkout -b issue-$1-<title>`
+3. **Plan**: Use TodoWrite to break down the work
+```
+
+### 2. Show Don't Tell
+
+Include actual commands and expected outputs:
+
+**Telling:**
+```markdown
+List the open issues.
+```
+
+**Showing:**
+```markdown
+Fetch all open issues and format as table:
+| # | Title | Author |
+|---|-------|--------|
+```
+
+### 3. Always Ask Before Acting
+
+Never modify resources without user approval:
+
+```markdown
+4. **Present plan** for approval
+5. **If approved**, create the issues
+```
+
+### 4. Handle Edge Cases
+
+Consider what happens when things are empty or unexpected:
+
+```markdown
+## If no argument (groom all):
+1. **List open issues**
+2. If no issues found, report "No open issues to groom"
+3. Otherwise, **review each** against checklist
+```
+
+### 5. Provide Helpful Output
+
+End with useful information:
+
+```markdown
+8. **Present summary** with:
+   - Links to created issues
+   - Dependency graph
+   - Suggested next steps
+```
+
+### 6. Keep Commands Focused
+
+One command = one workflow. If doing multiple unrelated things, split into separate commands.
+
+**Too broad:**
+```markdown
+# Manage Everything
+Handle issues, PRs, deployments, and documentation...
+```
+
+**Focused:**
+```markdown
+# Review PR #$1
+Review and take action on a pull request...
+```
+
+## When to Create a Command
+
+Create a command when you have:
+
+1. **Repeatable workflow**: Same steps used multiple times
+2. **User-initiated action**: User explicitly triggers it
+3. **Clear start and end**: Workflow has defined boundaries
+4. **Consistent behavior needed**: Should work the same every time
+
+### Signs You Need a New Command
+
+- You're explaining the same workflow repeatedly
+- Users would benefit from a single invocation
+- Multiple tools need orchestration
+- Approval checkpoints are needed
+
+### Signs You Don't Need a Command
+
+- It's a one-time action
+- No workflow orchestration needed
+- A skill reference is sufficient
+- An agent could handle it autonomously
+
+## Command Lifecycle
+
+### 1. Design
+
+Define the workflow:
+- What triggers it?
+- What arguments does it need?
+- What steps are involved?
+- Where are approval points?
+- What does success look like?
+
+### 2. Implement
+
+Create the command file:
+- Clear frontmatter
+- Step-by-step workflow
+- Skill references where needed
+- Approval checkpoints
+- Output formatting
+
+### 3. Test
+
+Verify the workflow:
+- Run with typical arguments
+- Test edge cases (no args, invalid args)
+- Confirm approval points work
+- Check output formatting
+
+### 4. Document
+
+Update references:
+- Add to ARCHITECTURE.md table
+- Update README if user-facing
+- Note any skill/agent dependencies
+
+## Checklist: Before Submitting a New Command
+
+### Structure
+- [ ] File is at `commands/<name>.md`
+- [ ] Name follows kebab-case verb convention
+
+### 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
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md): How commands fit into the overall system
+- [writing-skills.md](writing-skills.md): Creating skills that commands reference
+- [writing-agents.md](writing-agents.md): Creating agents that commands spawn
+- [VISION.md](../VISION.md): The philosophy behind composable components

docs/writing-skills.md

@@ -0,0 +1,578 @@
+# Writing Skills
+
+A guide to creating reusable knowledge modules for the Claude Code AI workflow system.
+
+> **Official Documentation**: For the most up-to-date information, see https://code.claude.com/docs/en/skills
+
+## What is a Skill?
+
+Skills are **model-invoked knowledge modules**—Claude automatically applies them when your request matches their description. Unlike commands (which require explicit `/command` invocation), skills are triggered automatically based on semantic matching.
+
+## YAML Frontmatter (Required)
+
+Every `SKILL.md` file **must** start with YAML frontmatter. This is how Claude discovers and triggers skills.
+
+### Format Requirements
+
+- Must start with `---` on **line 1** (no blank lines before it)
+- Must end with `---` before the markdown content
+- Use spaces for indentation (not tabs)
+
+### Required Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | **Yes** | Lowercase letters, numbers, and hyphens only (max 64 chars). Should match directory name. |
+| `description` | **Yes** | What the skill does and when to use it (max 1024 chars). **This is critical for triggering.** |
+
+### Optional Fields
+
+| Field | Description |
+|-------|-------------|
+| `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., `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
+
+The `description` field determines when Claude applies the skill. A good description answers:
+
+1. **What does this skill do?** List specific capabilities.
+2. **When should Claude use it?** Include trigger terms users would mention.
+
+**Bad (too vague):**
+```yaml
+description: Helps with documents
+```
+
+**Good (specific with trigger terms):**
+```yaml
+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.
+```
+
+### Example Frontmatter
+
+```yaml
+---
+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)
+
+[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:
+
+```yaml
+---
+name: code-reviewer
+description: Review code for quality and best practices
+skills: gitea, code-review
+---
+```
+
+## File Structure
+
+Skills live in the `skills/` directory, each in its own folder:
+
+```
+skills/
+├── gitea/
+│   └── SKILL.md
+├── issue-writing/
+│   └── SKILL.md
+├── backlog-grooming/
+│   └── SKILL.md
+└── roadmap-planning/
+    └── SKILL.md
+```
+
+### Why SKILL.md?
+
+The uppercase `SKILL.md` filename:
+- Makes the skill file immediately visible in directory listings
+- Follows a consistent convention across all skills
+- Clearly identifies the primary file in a skill folder
+
+### Supporting Files (Optional)
+
+A skill folder can contain additional files if needed:
+
+```
+skills/
+└── complex-skill/
+    ├── SKILL.md           # Main skill document (required)
+    ├── templates/         # Template files
+    │   └── example.md
+    └── examples/          # Extended examples
+        └── case-study.md
+```
+
+However, prefer keeping everything in `SKILL.md` when possible—it's easier to maintain and reference.
+
+## Skill Document Structure
+
+A well-structured `SKILL.md` follows this pattern:
+
+```markdown
+# Skill Name
+
+Brief description of what this skill covers.
+
+## Core Concepts
+Explain the 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.
+```
+
+Not every skill needs all sections—include what's relevant. Some skills are primarily patterns (like `issue-writing`), others are reference-heavy (like `gitea`).
+
+## How Skills are Discovered and Triggered
+
+Skills are **model-invoked**: Claude decides which skills to use based on your request.
+
+### Discovery Process
+
+1. **At startup**: Claude loads only the `name` and `description` of each available skill
+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:
+
+```yaml
+---
+name: product-manager
+description: Manages backlog and roadmap
+skills: gitea, issue-writing, backlog-grooming, roadmap-planning
+---
+```
+
+**Important**: Built-in agents and the Task tool do not have access to skills. Only custom subagents with an explicit `skills` field can use them.
+
+### Skills Can Reference Other Skills
+
+Skills can mention other skills for related knowledge:
+
+```markdown
+# Roadmap Planning
+
+...
+
+When creating issues, follow the patterns in the **issue-writing** skill.
+Use **gitea** commands to create the issues.
+```
+
+This creates a natural knowledge hierarchy without duplicating content.
+
+## Naming Conventions
+
+### Skill Folder Names
+
+- Use **kebab-case**: `issue-writing`, `backlog-grooming`
+- Be **descriptive**: name should indicate the skill's domain
+- Be **concise**: 2-3 words is ideal
+- Avoid generic names: `utils`, `helpers`, `common`
+
+Good names:
+- `gitea` - Tool-specific knowledge
+- `issue-writing` - Activity-focused
+- `backlog-grooming` - Process-focused
+- `roadmap-planning` - Task-focused
+
+### Skill Titles
+
+The H1 title in `SKILL.md` should match the folder name in Title Case:
+
+| Folder | Title |
+|--------|-------|
+| `gitea` | Forgejo CLI (fj) |
+| `issue-writing` | Issue Writing |
+| `backlog-grooming` | Backlog Grooming |
+| `roadmap-planning` | Roadmap Planning |
+
+## Best Practices
+
+### 1. Keep Skills Focused
+
+Each skill should cover **one domain, one concern**. If your skill document is getting long or covers multiple unrelated topics, consider splitting it.
+
+**Too broad:**
+```markdown
+# Project Management
+How to manage issues, PRs, releases, and documentation...
+```
+
+**Better:**
+```markdown
+# Issue Writing
+How to write clear, actionable issues.
+```
+
+### 2. Be Specific, Not Vague
+
+Provide concrete patterns, not abstract principles.
+
+**Vague:**
+```markdown
+## Writing Good Titles
+Titles should be clear and descriptive.
+```
+
+**Specific:**
+```markdown
+## Writing Good Titles
+- Start with action verb: "Add", "Fix", "Update", "Remove"
+- Be specific: "Add user authentication" not "Auth stuff"
+- Keep under 60 characters
+```
+
+### 3. Include Actionable Examples
+
+Every guideline should have an example showing what it looks like in practice.
+
+```markdown
+### Acceptance Criteria
+
+Good criteria are:
+- **Specific**: "User sees error message" not "Handle errors"
+- **Testable**: Can verify pass/fail
+- **User-focused**: What the user experiences
+
+Examples:
+- [ ] Login form validates email format before submission
+- [ ] Invalid credentials show "Invalid email or password" message
+- [ ] Successful login redirects to dashboard
+```
+
+### 4. Use Templates for Repeatability
+
+When the skill involves creating structured content, provide copy-paste templates:
+
+```markdown
+### Feature Request Template
+
+\```markdown
+## Summary
+What feature and why it's valuable.
+
+## Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Context
+Additional background or references.
+\```
+```
+
+### 5. Include Checklists for Verification
+
+Checklists help ensure consistent quality:
+
+```markdown
+## Grooming Checklist
+
+For each issue, verify:
+- [ ] Starts with action verb
+- [ ] Has acceptance criteria
+- [ ] Scope is clear
+- [ ] Dependencies identified
+```
+
+### 6. Document Common Mistakes
+
+Help avoid pitfalls by documenting what goes wrong:
+
+```markdown
+## Common Mistakes
+
+### Vague Titles
+- Bad: "Fix bug"
+- Good: "Fix login form validation on empty email"
+
+### Missing Acceptance Criteria
+Every issue needs specific, testable criteria.
+```
+
+### 7. Keep It Current
+
+Skills should reflect current practices. When workflows change:
+- Update the skill document
+- Remove obsolete patterns
+- Add new best practices
+
+## Annotated Examples
+
+Let's examine the existing skills to understand effective patterns.
+
+### Example 1: gitea (Tool Reference)
+
+The `gitea` skill is a **tool reference**—it documents how to use a specific CLI tool.
+
+```markdown
+# Forgejo CLI (fj)
+
+Command-line interface for interacting with Forgejo repositories.
+
+## Authentication
+The `tea` CLI authenticates via `tea auth login`. Credentials are stored locally.
+
+## Common Commands
+
+### Issues
+\```bash
+# List issues
+tea issue search -s open              # Open issues
+tea issue search -s closed            # Closed issues
+...
+\```
+```
+
+**Key patterns:**
+- Organized by feature area (Issues, Pull Requests, Repository)
+- Includes actual command syntax with comments
+- Covers common use cases, not exhaustive documentation
+- Tips section for non-obvious behaviors
+
+### Example 2: issue-writing (Process Knowledge)
+
+The `issue-writing` skill is **process knowledge**—it teaches how to do something well.
+
+```markdown
+# Issue Writing
+
+How to write clear, actionable issues.
+
+## Issue Structure
+
+### Title
+- Start with action verb: "Add", "Fix", "Update", "Remove"
+- Be specific: "Add user authentication" not "Auth stuff"
+- Keep under 60 characters
+
+### Description
+\```markdown
+## Summary
+One paragraph explaining what and why.
+
+## Acceptance Criteria
+- [ ] Specific, testable requirement
+...
+\```
+```
+
+**Key patterns:**
+- Clear guidelines with specific rules
+- Templates for different issue types
+- Good/bad examples for each guideline
+- Covers the full lifecycle (structure, criteria, labels, dependencies)
+
+### Example 3: backlog-grooming (Workflow Checklist)
+
+The `backlog-grooming` skill is a **workflow checklist**—it provides a systematic process.
+
+```markdown
+# Backlog Grooming
+
+How to review and improve existing issues.
+
+## Grooming Checklist
+
+For each issue, verify:
+
+### 1. Title Clarity
+- [ ] Starts with action verb
+- [ ] Specific and descriptive
+- [ ] Understandable without reading description
+...
+```
+
+**Key patterns:**
+- Structured as a checklist with categories
+- Each item is a yes/no verification
+- Includes workflow steps (Grooming Workflow section)
+- Questions to guide decision-making
+
+### Example 4: roadmap-planning (Strategy Guide)
+
+The `roadmap-planning` skill is a **strategy guide**—it teaches how to think about a problem.
+
+```markdown
+# Roadmap Planning
+
+How to plan features and create issues for implementation.
+
+## Planning Process
+
+### 1. Understand the Goal
+- What capability or improvement is needed?
+- Who benefits and how?
+- What's the success criteria?
+
+### 2. Break Down the Work
+- Identify distinct components
+- Define boundaries between pieces
+...
+```
+
+**Key patterns:**
+- Process-oriented with numbered steps
+- Multiple breakdown strategies (by layer, by user story, by component)
+- Concrete examples showing the pattern applied
+- Questions to guide planning decisions
+
+## When to Create a New Skill
+
+Create a skill when you find yourself:
+
+1. **Explaining the same concepts repeatedly** across different conversations
+2. **Wanting consistent quality** in a specific area
+3. **Building up domain expertise** that should persist
+4. **Needing a reusable reference** for commands or agents
+
+### Signs You Need a New Skill
+
+- You're copy-pasting the same guidelines
+- Multiple commands need the same knowledge
+- Quality is inconsistent without explicit guidance
+- There's a clear domain that doesn't fit existing skills
+
+### Signs You Don't Need a New Skill
+
+- The knowledge is only used once
+- It's already covered by an existing skill
+- It's too generic to be actionable
+- It's better as part of a command's instructions
+
+## Skill Lifecycle
+
+### 1. Draft
+
+Start with the essential content:
+- Core patterns and templates
+- Key guidelines
+- A few examples
+
+### 2. Refine
+
+As you use the skill, improve it:
+- Add examples from real usage
+- Clarify ambiguous guidelines
+- Remove unused content
+
+### 3. Maintain
+
+Keep skills current:
+- Update when practices change
+- Remove obsolete patterns
+- Add newly discovered best practices
+
+## Checklist: Before Submitting a New Skill
+
+### Frontmatter (Critical)
+- [ ] YAML frontmatter starts on line 1 (no blank lines before `---`)
+- [ ] `name` field uses lowercase letters, numbers, and hyphens only
+- [ ] `name` matches the directory name
+- [ ] `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
+
+### Content Quality
+- [ ] Skill focuses on a single domain
+- [ ] Guidelines are specific and actionable
+- [ ] Examples illustrate each major point
+- [ ] Templates are provided where appropriate
+- [ ] Common mistakes are documented
+
+### Integration
+- [ ] Skill is listed in relevant subagent `skills` fields if needed
+
+## See Also
+
+- [ARCHITECTURE.md](../ARCHITECTURE.md): How skills fit into the overall system
+- [VISION.md](../VISION.md): The philosophy behind composable components

index.ts

@@ -1 +0,0 @@
-console.log("Hello via Bun!");

learnings/README.md

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

manifesto.md

@@ -0,0 +1,94 @@
+# Manifesto
+
+## Who We Are
+
+We are a small, focused team building tools that make work easier. We believe software should support business processes without requiring everyone to become a developer. We build in public - sharing our AI-augmented development practices, tools, and learnings with the developer community.
+
+## Who We Serve
+
+### Domain Experts
+Business analysts, operations managers, process owners - people who understand their domain deeply but shouldn't need to code. They want to create and evolve software solutions that support their processes directly, without waiting for IT or hiring developers.
+
+### Agencies & Consultancies
+Teams building solutions for clients using our platform. They need speed, consistency, and the ability to deliver maintainable solutions across engagements. Every efficiency gain multiplies across projects.
+
+### Organizations
+From small businesses to enterprises - any organization that needs maintainable software to support their business processes. They benefit from solutions built on our platform, whether created by their own domain experts or by agencies on their behalf.
+
+## What They're Trying to Achieve
+
+- "Help me create software that supports my business process without learning to code"
+- "Help me evolve my solutions as my business changes"
+- "Help me deliver maintainable solutions to clients faster"
+- "Help me get software that actually fits how we work"
+- "Help me reduce dependency on developers for business process changes"
+
+## What We Believe
+
+### Empowering Domain Experts
+
+We believe the people closest to business problems should be able to solve them:
+
+- **Domain expertise matters most.** The person who understands the process deeply is better positioned to design the solution than a developer translating requirements.
+
+- **Low-code removes barriers.** When domain experts can create and evolve solutions directly, organizations move faster and get better-fitting software.
+
+- **Maintainability enables evolution.** Business processes change. Software that supports them must be easy to adapt without starting over.
+
+- **Technology should disappear.** The best tools get out of the way. Domain experts should think about their processes, not about technology.
+
+### AI-Augmented Development
+
+We believe AI fundamentally changes how software is built:
+
+- **Developers become orchestrators.** The role shifts from writing every line to directing, reviewing, and refining. The human provides judgment, context, and intent. AI handles execution and recall.
+
+- **Repetitive tasks should be automated.** If you do something more than twice, encode it. Commits, PR creation, issue management, code review - these should flow, not interrupt.
+
+- **AI amplifies individuals.** A solo developer with good AI tooling can accomplish what used to require a team. Small teams can tackle problems that used to need departments.
+
+- **Knowledge belongs in systems, not heads.** Best practices, patterns, and learnings should be encoded where AI can apply them. Tribal knowledge is a liability.
+
+- **Iteration speed is a competitive advantage.** The faster you can go from idea to deployed code to learning, the faster you improve. AI collapses the feedback loop.
+
+### Quality Without Ceremony
+
+- Ship small, ship often
+- Automate verification, not just generation
+- Good defaults beat extensive configuration
+- Working software over comprehensive documentation
+
+### Sustainable Pace
+
+- Tools should reduce cognitive load, not add to it
+- Automation should free humans for judgment calls
+- The goal is flow, not burnout
+
+### Resource Efficiency
+
+- Software should run well on modest hardware
+- Cloud cost and energy consumption matter
+- ARM64-native where possible - better performance per watt
+- Bloated software is a sign of poor engineering, not rich features
+
+## Guiding Principles
+
+1. **Encode, don't document.** If something is important enough to write down, it's important enough to encode into a skill, command, or agent that can act on it.
+
+2. **Small teams, big leverage.** Design for amplification. Every tool, pattern, and practice should multiply what individuals can accomplish.
+
+3. **Opinionated defaults, escape hatches available.** Make the right thing easy. Make customization possible but not required.
+
+4. **Learn in public.** Capture learnings. Update the system. Share what works.
+
+5. **Ship to learn.** Prefer shipping something imperfect and learning from reality over planning for perfection.
+
+## Non-Goals
+
+- **Replacing human judgment.** AI and low-code tools augment human decision-making; they don't replace it. Domain expertise, critical thinking, and understanding of business context remain human responsibilities.
+
+- **Supporting every tool and platform.** We go deep on our chosen stack rather than shallow on everything.
+
+- **Building generic software.** We focus on maintainable solutions for business processes, not general-purpose applications.
+
+- **Comprehensive documentation for its own sake.** We encode knowledge into actionable systems. Docs exist to explain the "why," not to duplicate what the system already does.

models.yaml

@@ -1,26 +0,0 @@
-manager:
-  memory_budget: 450
-  contention_policy:
-    strategy: wait_then_preempt
-    wait_timeout_s: 45
-    preempt_after_s: 15
-
-models:
-  - name: Qwen-Coder-Next
-    model: mlx-community/Qwen3-Coder-Next-4bit
-    estimated_memory_gb: 50
-    reasoning_parser: qwen3
-
-  - name: Qwen3.6
-    model: mlx-community/Qwen3.6-35B-A3B-6bit
-    estimated_memory_gb: 40
-    reasoning_parser: qwen3
-
-  - name: gemma
-    model: mlx-community/gemma-4-31b-it-8bit
-    estimated_memory_gb: 40
-    reasoning_parser: gemma4
-
-  - name: MiniMax-M3
-    model: pipenetwork/MiniMax-M3-MLX-mixed-3_6bit
-    estimated_memory_gb: 200

package.json

@@ -1,12 +0,0 @@
-{
-  "name": "architecture",
-  "module": "index.ts",
-  "type": "module",
-  "private": true,
-  "devDependencies": {
-    "@types/bun": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "^5"
-  }
-}

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

sample_opencode.json

@@ -1,35 +0,0 @@
-{
-  "$schema": "https://opencode.ai/config.json",
-  "provider": {
-    "odin": {
-      "npm": "@ai-sdk/anthropic",
-      "name": "Odin",
-      "options": {
-        "baseURL": "http://192.168.2.49:12000/v1",
-        "apiKey": "changeme"
-      },
-      "models": {
-        "Qwen-Coder-Next": {
-          "name": "Qwen-Coder-Next",
-          "tool_call": true,
-          "options": {
-            "temperature": 1.0,
-            "top_p": 0.95
-          }
-        },
-        "Qwen3.6": {
-          "name": "Qwen3.6",
-          "tool_call": true
-        },
-        "gemma": {
-          "name": "gemma",
-          "tool_call": true
-        },
-        "MiniMax-M3": {
-          "name": "MiniMax-M3",
-          "tool_call": true
-        }
-      }
-    }
-  }
-}

scripts/pre-commit-checks.sh

@@ -0,0 +1,50 @@
+#!/bin/bash
+# Pre-commit validation script for Claude Code
+# Validates YAML, checks for secrets, validates K8s manifests
+
+set -e
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only 2>/dev/null || echo "")
+
+if [ -z "$STAGED_FILES" ]; then
+  exit 0
+fi
+
+# Check for potential secrets in staged files
+echo "Checking for potential secrets..."
+SECRET_PATTERN='(password|secret|token|api_key|apikey|private_key).*[=:].{20,}'
+if echo "$STAGED_FILES" | xargs grep -l -iE "$SECRET_PATTERN" 2>/dev/null | grep -v '.sops.yaml' | grep -v 'secret.*\.enc\.yaml'; then
+  echo "WARNING: Potential secrets detected in staged files (excluding SOPS-encrypted files)"
+  echo "Please verify these are encrypted or not actual secrets."
+fi
+
+# Validate YAML syntax
+echo "Validating YAML syntax..."
+for file in $(echo "$STAGED_FILES" | grep -E '\.ya?ml$'); do
+  if [ -f "$file" ]; then
+    if ! python3 -c "import yaml; yaml.safe_load(open('$file'))" 2>/dev/null; then
+      echo "ERROR: Invalid YAML syntax: $file"
+      exit 1
+    fi
+  fi
+done
+
+# Validate Kubernetes manifests (if kubectl available)
+if command -v kubectl &>/dev/null; then
+  echo "Validating Kubernetes manifests..."
+  for file in $(echo "$STAGED_FILES" | grep -E '\.ya?ml$'); do
+    if [ -f "$file" ] && grep -q "^kind:" "$file" 2>/dev/null; then
+      # Skip SOPS-encrypted files and kustomization files
+      if echo "$file" | grep -qE '(\.sops\.yaml|\.enc\.yaml|kustomization\.yaml)$'; then
+        continue
+      fi
+      if ! kubectl apply --dry-run=client -f "$file" 2>/dev/null; then
+        echo "WARNING: Kubernetes validation failed: $file (may be expected for partial manifests)"
+      fi
+    fi
+  done
+fi
+
+echo "Pre-commit checks passed."
+exit 0

settings.json

@@ -1,4 +1,5 @@
 {
+  "model": "opus",
   "permissions": {
     "allow": [
       "Bash(git:*)",
@@ -9,6 +10,13 @@
       "WebSearch"
     ]
   },
+  "statusLine": {
+    "type": "command",
+    "command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\""
+  },
+  "enabledPlugins": {
+    "gopls-lsp@claude-plugins-official": true
+  },
   "hooks": {
     "PreToolUse": [
       {
@@ -22,14 +30,5 @@
         ]
       }
     ]
-  },
-  "statusLine": {
-    "type": "command",
-    "command": "input=$(cat); current_dir=$(echo \"$input\" | jq -r '.workspace.current_dir'); model=$(echo \"$input\" | jq -r '.model.display_name'); style=$(echo \"$input\" | jq -r '.output_style.name'); git_info=\"\"; if [ -d \"$current_dir/.git\" ]; then cd \"$current_dir\" && branch=$(git branch --show-current 2>/dev/null) && status=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ') && git_info=\" [$branch$([ \"$status\" != \"0\" ] && echo \"*\")]\"; fi; printf \"\\033[2m$(whoami)@$(hostname -s) $(basename \"$current_dir\")$git_info | $model ($style)\\033[0m\"",
-    "padding": 0
-  },
-  "enabledPlugins": {
-    "gopls-lsp@claude-plugins-official": true
-  },
-  "model": "opus"
+  }
 }

skills/backlog-grooming/SKILL.md

@@ -0,0 +1,99 @@
+---
+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
+
+How to review and improve existing issues.
+
+## Grooming Checklist
+
+For each issue, verify:
+
+### 1. Title Clarity
+- [ ] Starts with action verb
+- [ ] Specific and descriptive
+- [ ] Understandable without reading description
+
+### 2. Description Quality
+- [ ] Has clear summary
+- [ ] Explains the "why"
+- [ ] Provides enough context
+
+### 3. Acceptance Criteria
+- [ ] Criteria exist
+- [ ] Each criterion is testable
+- [ ] Criteria are specific (not vague)
+- [ ] Complete set (nothing missing)
+
+### 4. Scope
+- [ ] Not too broad (can complete in reasonable time)
+- [ ] Not too narrow (meaningful unit of work)
+- [ ] Clear boundaries (what's included/excluded)
+
+### 5. Dependencies
+- [ ] Dependencies identified in description
+- [ ] Dependencies formally linked (`tea issues deps list <number>`)
+- [ ] No circular dependencies
+- [ ] Blocking issues are tracked
+
+To check/fix dependencies:
+```bash
+tea issues deps list <number>           # View current dependencies
+tea issues deps add <issue> <blocker>   # Add missing dependency
+tea issues deps remove <issue> <dep>    # Remove incorrect dependency
+```
+
+### 6. Labels
+- [ ] Type label (bug/feature/etc)
+- [ ] Priority if applicable
+- [ ] Component labels if applicable
+
+## Common Issues to Fix
+
+### Vague Titles
+- Bad: "Fix bug"
+- Good: "Fix login form validation on empty email"
+
+### Missing Acceptance Criteria
+Add specific, testable criteria based on the description.
+
+### Scope Creep
+If issue covers multiple features, split into separate issues.
+
+### Stale Issues
+- Close if no longer relevant
+- Update if context has changed
+- Add "needs-triage" label if unclear
+
+### Duplicate Issues
+- Close duplicate with reference to original
+- Merge relevant details into original
+
+## Grooming Workflow
+
+Use the gitea skill for issue operations.
+
+1. **Fetch open issues**
+2. **Review each issue** against checklist
+3. **Improve or flag** issues that need work
+4. **Update issue** with improvements
+5. **Add labels** as needed
+
+## Questions to Ask
+
+When grooming, consider:
+- "Could a developer start work on this today?"
+- "How will we know when this is done?"
+- "Is the scope clear?"
+- "Are dependencies explicit?"
+
+## Batch Grooming
+
+When grooming multiple issues:
+1. List all open issues
+2. Categorize by quality (ready, needs-work, stale)
+3. Focus on "needs-work" issues
+4. Present summary of changes made

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

@@ -0,0 +1,205 @@
+---
+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
+
+Guidelines for reviewing code changes in pull requests.
+
+## Review Categories
+
+### Code Quality
+
+Look for:
+- **Readability**: Clear naming, logical structure, appropriate comments
+- **Maintainability**: Easy to modify, follows DRY, single responsibility
+- **Complexity**: Avoid deep nesting, overly long functions, complex conditionals
+- **Dead code**: Unused variables, unreachable code, commented-out blocks
+
+Questions to ask:
+- Can someone unfamiliar with this code understand it quickly?
+- Would I be comfortable maintaining this code?
+- Does this follow existing patterns in the codebase?
+
+### Potential Bugs
+
+Look for:
+- **Edge cases**: Empty arrays, null values, boundary conditions
+- **Logic errors**: Off-by-one, incorrect operators, inverted conditions
+- **Race conditions**: Async operations, shared state
+- **Resource leaks**: Unclosed connections, missing cleanup
+- **Error handling**: Unhandled exceptions, silent failures
+
+Questions to ask:
+- What happens with unexpected input?
+- Are all error paths handled appropriately?
+- Could concurrent execution cause issues?
+
+### Security Concerns
+
+Look for:
+- **Injection**: SQL, command, XSS vulnerabilities
+- **Authentication**: Bypasses, weak validation
+- **Authorization**: Missing permission checks
+- **Data exposure**: Logging secrets, exposing internals
+- **Dependencies**: Known vulnerabilities in imports
+
+Questions to ask:
+- Could an attacker exploit this?
+- Is user input properly validated and sanitized?
+- Are secrets properly protected?
+
+### Style & Consistency
+
+Look for:
+- **Naming conventions**: Match existing codebase style
+- **Formatting**: Consistent indentation, spacing
+- **File organization**: Logical grouping, appropriate location
+- **Import order**: Following project conventions
+
+Note: Style issues are lower priority than functional concerns.
+
+### Test Coverage
+
+Look for:
+- **Missing tests**: New functionality without tests
+- **Edge cases**: Boundary conditions not tested
+- **Error paths**: Exception handling not verified
+- **Integration**: Component interactions not covered
+
+Questions to ask:
+- Would these tests catch a regression?
+- Are the assertions meaningful?
+- Do tests cover the acceptance criteria?
+
+## Review Process
+
+1. **Understand context**: Read PR description and linked issues
+2. **High-level scan**: Understand overall structure and approach
+3. **Detailed review**: Go through changes file by file
+4. **Consider impact**: Think about side effects and dependencies
+5. **Provide feedback**: Be constructive and specific
+
+## Writing Review Comments
+
+### Be Constructive
+- Explain *why* something is an issue
+- Suggest alternatives when possible
+- Distinguish between blocking issues and suggestions
+
+### Be Specific
+- Reference exact lines or code blocks
+- Provide concrete examples
+- Link to relevant documentation or patterns
+
+### Be Kind
+- Phrase feedback as questions when appropriate
+- Acknowledge good solutions
+- Remember there's a person receiving this feedback
+
+## Example Review Comments
+
+### Code Quality
+
+**Good:**
+> `src/utils/parser.ts:45` - This function is doing three things: parsing, validating, and transforming. Consider splitting into `parse()`, `validate()`, and `transform()` to improve testability and make each responsibility clear.
+
+**Bad:**
+> This code is messy, please clean it up.
+
+### Potential Bugs
+
+**Good:**
+> `src/api/users.ts:23` - `users.find()` returns `undefined` when no match is found, but line 25 accesses `user.id` without a null check. This will throw when the user doesn't exist. Consider: `const user = users.find(...); if (!user) return null;`
+
+**Bad:**
+> This might crash.
+
+### Security
+
+**Good:**
+> `src/routes/search.ts:12` - The query parameter is interpolated directly into the SQL string, which allows SQL injection. Use parameterized queries instead: `db.query('SELECT * FROM items WHERE name = ?', [query])`
+
+**Bad:**
+> Security issue here.
+
+### Style
+
+**Good:**
+> `src/components/Button.tsx:8` - Minor: The codebase uses `camelCase` for event handlers (e.g., `handleClick`), but this uses `on_click`. Consider renaming for consistency.
+
+**Bad:**
+> Wrong naming convention.
+
+### Test Coverage
+
+**Good:**
+> The happy path is well tested. Consider adding a test for when `fetchUser()` rejects - the error handling in line 34 isn't currently covered.
+
+**Bad:**
+> Need more tests.
+
+### Positive Feedback
+
+**Good:**
+> Nice use of the builder pattern here - it makes the configuration much more readable than the previous approach with multiple boolean flags.
+
+## Verdict Criteria
+
+### LGTM (Looks Good To Me)
+- No blocking issues
+- Code meets quality standards
+- Tests are adequate
+- Ready to merge
+
+### Needs Changes
+- Minor issues that should be addressed
+- Style improvements
+- Missing tests for edge cases
+- Not blocking, but worth fixing
+
+### Blocking Issues
+- Security vulnerabilities
+- Logic errors that would cause bugs
+- Missing critical functionality
+- Breaking changes without migration
+
+## Review Comment Template
+
+```markdown
+## AI Code Review
+
+> This is an automated review generated by the code-reviewer agent.
+
+### Summary
+[1-2 sentence overall assessment of the changes]
+
+### Findings
+
+#### Code Quality
+- [Issue with specific file:line reference and explanation]
+- [Or "Code is well-structured and readable"]
+
+#### Potential Bugs
+- [Bug risk with explanation]
+- [Or "No obvious issues found"]
+
+#### Security Concerns
+- [Security issue with severity]
+- [Or "No security concerns identified"]
+
+#### Style Notes
+- [Style improvement suggestion]
+- [Or "Consistent with codebase conventions"]
+
+#### Test Coverage
+- [Missing test scenario]
+- [Or "Tests adequately cover changes"]
+
+### Verdict
+**[LGTM / Needs Changes / Blocking Issues]**
+
+[Brief explanation of verdict]
+```

skills/gitea/SKILL.md

@@ -0,0 +1,199 @@
+---
+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)
+
+Command-line interface for interacting with Gitea repositories.
+
+## Installation
+
+```bash
+brew install tea
+```
+
+## Authentication
+
+The `tea` CLI authenticates via `tea logins add`. Credentials are stored locally by tea.
+
+```bash
+tea logins add                       # Interactive login
+tea logins add --url <url> --token <token> --name <name>  # Non-interactive
+tea logins list                      # Show configured logins
+tea logins default <name>            # Set default login
+```
+
+## Configuration
+
+Config is stored at `~/Library/Application Support/tea/config.yml` (macOS).
+
+To avoid needing `--login` on every command, set defaults:
+
+```yaml
+preferences:
+    editor: false
+    flag_defaults:
+        remote: origin
+        login: git.flowmade.one
+```
+
+## Repository Detection
+
+`tea` automatically detects the repository from git remotes when run inside a git repository. Use `--remote <name>` to specify which remote to use.
+
+## Common Commands
+
+### Issues
+
+```bash
+# List issues
+tea issues                           # Open issues (default)
+tea issues --state all               # All issues
+tea issues --state closed            # Closed issues
+
+# View issue details
+tea issues <number>                  # Full issue details
+tea issues <number> --comments       # Include comments
+
+# Create issue
+tea issues create --title "<title>" --description "<body>"
+tea issues create -t "<title>" -d "<body>"
+
+# Edit issue
+tea issues edit <number> --title "<new-title>"
+tea issues edit <number> --description "<new-body>"
+
+# Close/reopen
+tea issues close <number>
+tea issues reopen <number>
+
+# Labels
+tea issues edit <number> --labels "bug,help wanted"
+
+# Dependencies
+tea issues deps list <number>              # List blockers for an issue
+tea issues deps add <issue> <blocker>      # Add dependency (issue is blocked by blocker)
+tea issues deps add 5 3                    # Issue #5 depends on #3
+tea issues deps add 5 owner/repo#3         # Cross-repo dependency
+tea issues deps remove <issue> <blocker>   # Remove a dependency
+```
+
+### Pull Requests
+
+```bash
+# List PRs
+tea pulls                            # Open PRs (default)
+tea pulls --state all                # All PRs
+tea pulls --state closed             # Closed/merged PRs
+
+# View PR
+tea pulls <number>                   # PR details
+tea pulls <number> --comments        # Include comments
+
+# View PR diff (tea doesn't have a diff command, use git)
+tea pulls checkout <number>          # First checkout the PR branch
+git diff main...HEAD                 # Diff against main branch
+
+# Create PR
+tea pulls create --title "<title>" --description "<body>"
+tea pulls create -t "<title>" -d "<body>"
+tea pulls create -t "<title>" -d "Closes #<issue>"
+tea pulls create --head <branch> --base main -t "<title>"
+
+# Checkout PR locally
+tea pulls checkout <number>
+
+# Review/Approve
+tea pulls approve <number>           # Approve PR (LGTM)
+tea pulls reject <number>            # Request changes
+tea pulls review <number>            # Interactive review
+
+# Merge
+tea pulls merge <number>                      # Default merge
+tea pulls merge <number> --style squash       # Squash commits
+tea pulls merge <number> --style rebase       # Rebase commits
+tea pulls merge <number> --style rebase-merge # Rebase then merge
+
+# Clean up after merge
+tea pulls clean <number>             # Delete local & remote branch
+```
+
+### Repository
+
+```bash
+tea repos                            # List repos
+tea repos <owner>/<repo>             # Repository info
+tea clone <owner>/<repo>             # Clone repository
+```
+
+### Comments
+
+```bash
+# Add comment to issue or PR
+tea comment <number> "<comment body>"
+tea comment 3 "LGTM, ready to merge"
+
+# Multiline comments (use quoted strings with literal newlines)
+tea comment 3 "## Review Summary
+
+- Code looks good
+- Tests pass"
+```
+
+> **Warning**: Do not use heredoc syntax `$(cat <<'EOF'...EOF)` with `tea comment` - it causes the command to be backgrounded and fail silently.
+
+### Notifications
+
+```bash
+tea notifications                    # List notifications
+tea notifications --mine             # Only participating
+```
+
+## Output Formatting
+
+Most commands support `--output` or `-o` flag:
+- `-o simple` - Plain text
+- `-o table` - Tabular format (default)
+- `-o json` - Machine-readable JSON
+- `-o yaml` - YAML format
+- `-o csv` - CSV format
+
+## Specifying Remote/Login
+
+```bash
+tea issues --remote gitea            # Use specific git remote
+tea issues --login myserver          # Use specific login
+tea issues -r owner/repo             # Specify repo directly
+```
+
+## Tips
+
+- **View single issue**: Use `tea issues <number>` (NOT `tea issues view <number>` - there is no `view` subcommand)
+- **PR description flag**: Use `--description` or `-d` (NOT `--body` like gh CLI)
+- Always verify you're in the correct repository before running commands
+- Use `tea issues` to find issue numbers before viewing/editing
+- Reference issues in PR bodies with `Closes #N` for auto-linking
+- Use `--remote gitea` when you have multiple remotes (e.g., origin + gitea)
+- The `tea pulls checkout` command is handy for reviewing PRs locally
+
+## Actions / CI
+
+```bash
+# List workflow runs
+tea actions runs                     # List all workflow runs
+tea actions runs -o json             # JSON output for parsing
+
+# List jobs for a run
+tea actions jobs <run-id>            # Show jobs for a specific run
+tea actions jobs <run-id> -o json    # JSON output
+
+# Get job logs
+tea actions logs <job-id>            # Display logs for a job
+
+# Full workflow: find failed job logs
+tea actions runs                     # Find the run ID
+tea actions jobs <run-id>            # Find the job ID
+tea actions logs <job-id>            # View the logs
+```

skills/issue-writing/SKILL.md

@@ -0,0 +1,156 @@
+---
+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
+
+How to write clear, actionable issues.
+
+## Issue Structure
+
+### Title
+- Start with action verb: "Add", "Fix", "Update", "Remove", "Refactor"
+- Be specific: "Add user authentication" not "Auth stuff"
+- Keep under 60 characters when possible
+
+### Description
+
+```markdown
+## Summary
+One paragraph explaining what and why.
+
+## Acceptance Criteria
+- [ ] Specific, testable requirement
+- [ ] Another requirement
+- [ ] User can verify this works
+
+## Context
+Additional background, links, or references.
+
+## Technical Notes (optional)
+Implementation hints or constraints.
+```
+
+## Writing Acceptance Criteria
+
+Good criteria are:
+- **Specific**: "User sees error message" not "Handle errors"
+- **Testable**: Can verify pass/fail
+- **User-focused**: What the user experiences
+- **Independent**: Each stands alone
+
+Examples:
+```markdown
+- [ ] Login form validates email format before submission
+- [ ] Invalid credentials show "Invalid email or password" message
+- [ ] Successful login redirects to dashboard
+- [ ] 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
+```markdown
+## Summary
+Description of the bug.
+
+## Steps to Reproduce
+1. Go to...
+2. Click...
+3. Observe...
+
+## Expected Behavior
+What should happen.
+
+## Actual Behavior
+What happens instead.
+
+## Environment
+- Browser/OS/Version
+```
+
+### Feature Request
+```markdown
+## Summary
+What feature and why it's valuable.
+
+## Acceptance Criteria
+- [ ] ...
+
+## User Story (optional)
+As a [role], I want [capability] so that [benefit].
+```
+
+### Technical Task
+```markdown
+## Summary
+What technical work needs to be done.
+
+## Scope
+- Include: ...
+- Exclude: ...
+
+## Acceptance Criteria
+- [ ] ...
+```
+
+## Labels
+
+Use labels to categorize:
+- `bug`, `feature`, `enhancement`, `refactor`
+- `priority/high`, `priority/low`
+- Component labels specific to project
+
+## Dependencies
+
+Identify and link dependencies when creating issues:
+
+1. **In the description**, document dependencies:
+   ```markdown
+   ## Dependencies
+   - Depends on #12 (must complete first)
+   - Related to #15 (informational)
+   ```
+
+2. **After creating the issue**, formally link blockers using tea CLI:
+   ```bash
+   tea issues deps add <this-issue> <blocker-issue>
+   tea issues deps add 5 3    # Issue #5 is blocked by #3
+   ```
+
+This creates a formal dependency graph that tools can query.

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

@@ -0,0 +1,163 @@
+---
+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
+
+How to plan features and create issues for implementation.
+
+## Planning Process
+
+### 1. Understand the Goal
+- What capability or improvement is needed?
+- Who benefits and how?
+- What's the success criteria?
+
+### 2. Break Down the Work
+- Identify distinct components
+- Define boundaries between pieces
+- Aim for issues that are:
+  - Completable in 1-3 focused sessions
+  - Independently testable
+  - Clear in scope
+
+### 3. Identify Dependencies
+- Which pieces must come first?
+- What can be parallelized?
+- Are there external blockers?
+
+### 4. Create Issues
+- Follow issue-writing patterns
+- 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
+```
+Feature: User Authentication
+├── Data layer: User model, password hashing
+├── API layer: Login/logout endpoints
+├── UI layer: Login form, session display
+└── Integration: Connect all layers
+```
+
+### By User Story
+```
+Feature: Shopping Cart
+├── Add item to cart
+├── View cart contents
+├── Update quantities
+├── Remove items
+└── Proceed to checkout
+```
+
+### By Technical Component
+```
+Feature: Real-time Updates
+├── WebSocket server setup
+├── Client connection handling
+├── Message protocol
+├── Reconnection logic
+└── Integration tests
+```
+
+## Issue Ordering
+
+### Dependency Chain
+Create issues in implementation order:
+1. Foundation (models, types, interfaces)
+2. Core logic (business rules)
+3. Integration (connecting pieces)
+4. Polish (error handling, edge cases)
+
+### Reference Pattern
+In issue descriptions:
+```markdown
+## Dependencies
+- Depends on #12 (user model)
+- Depends on #13 (API setup)
+```
+
+After creating issues, formally link dependencies:
+```bash
+tea issues deps add <issue> <blocker>
+tea issues deps add 14 12    # Issue #14 depends on #12
+tea issues deps add 14 13    # Issue #14 depends on #13
+```
+
+## Creating Issues
+
+Use the gitea skill for issue operations.
+
+### Single Issue
+Create with a descriptive title and structured body:
+- Summary section
+- Acceptance criteria (testable checkboxes)
+- Dependencies section referencing blocking issues
+
+### Batch Creation
+When creating multiple related issues:
+1. Plan all issues first
+2. Create in dependency order
+3. Update earlier issues with forward references
+
+## Roadmap View
+
+To see current roadmap:
+1. List open issues using the gitea skill
+2. Group by labels/milestones
+3. Identify blocked vs ready issues
+4. Prioritize based on dependencies and value
+
+## Planning Questions
+
+Before creating issues, answer:
+- "What's the minimum viable version?"
+- "What can we defer?"
+- "What are the riskiest parts?"
+- "How will we validate each piece?"

skills/vision-management/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: vision-management
+description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
+user-invocable: false
+---
+
+# Vision Management
+
+How to create, maintain, and evolve organizational direction at two levels: manifesto (organization) and vision (product).
+
+## Architecture
+
+| Level | Document | Purpose | Command | Location |
+|-------|----------|---------|---------|----------|
+| **Organization** | `manifesto.md` | Identity, shared personas, beliefs, principles | `/manifesto` | `../architecture/` (sibling repo) |
+| **Product** | `vision.md` | Product-specific personas, jobs, solution | `/vision` | Product repo root |
+| **Goals** | Gitea milestones | Measurable progress toward vision | `/vision goals` | Per repo |
+
+Product vision **inherits from and extends** the organization manifesto - it should never duplicate.
+
+---
+
+## Manifesto (Organization Level)
+
+The manifesto defines who we are as an organization. It lives in the architecture repo and applies across all products.
+
+### Manifesto Structure
+
+```markdown
+# Manifesto
+
+## Who We Are
+Organization identity - what makes us unique.
+
+## Who We Serve
+Shared personas across all products.
+- **Persona Name**: Description, context, constraints
+
+## What They're Trying to Achieve
+Jobs to be done at the organization level.
+- "Help me [outcome] without [pain]"
+
+## What We Believe
+Core beliefs that guide how we work.
+### [Belief Category]
+- Belief point
+- Belief point
+
+## Guiding Principles
+Decision-making rules that apply everywhere.
+1. **Principle**: Explanation
+
+## Non-Goals
+What the organization explicitly does NOT do.
+- **Non-goal**: Why
+```
+
+### When to Update Manifesto
+
+- **Rarely** - this is foundational identity
+- When core beliefs change
+- When adding/removing personas served
+- When adding non-goals based on learnings
+
+### Creating a Manifesto
+
+1. Define organization identity (Who We Are)
+2. Identify shared personas (2-4 max)
+3. Articulate organization-level jobs to be done
+4. Document core beliefs (especially about AI/development)
+5. Establish guiding principles
+6. Define non-goals
+
+---
+
+## Vision (Product Level)
+
+The vision defines what a specific product does. It lives in each product repo and **extends the manifesto**.
+
+### Vision Structure
+
+```markdown
+# Vision
+
+This product vision builds on the [organization manifesto](../architecture/manifesto.md).
+
+## Who This Product Serves
+
+### [Persona Name]
+
+[Product-specific description]
+
+*Extends: [Org persona] (from manifesto)*
+
+## What They're Trying to Achieve
+
+These trace back to organization-level jobs:
+
+| Product Job | Enables Org Job |
+|-------------|-----------------|
+| "[Product-specific job]" | "[Org job from manifesto]" |
+
+## The Problem
+
+[Pain points this product addresses]
+
+## The Solution
+
+[How this product solves those problems]
+
+## Product Principles
+
+These extend the organization's guiding principles:
+
+### [Principle Name]
+
+[Description]
+
+*Extends: "[Org principle]"*
+
+## Non-Goals
+
+These extend the organization's non-goals:
+
+- **[Non-goal].** [Explanation]
+```
+
+### When to Update Vision
+
+- When product direction shifts
+- When adding/changing personas served by this product
+- When discovering new non-goals
+- After major learnings from retros
+
+### Creating a Product Vision
+
+1. **Start with the manifesto** - read it first
+2. Define product personas that extend org personas
+3. Identify product jobs that trace back to org jobs
+4. Articulate the problem this product solves
+5. Define the solution approach
+6. Set product-specific principles (noting what they extend)
+7. Document product non-goals
+8. Create initial milestones
+
+---
+
+## Inheritance Model
+
+```
+Manifesto (org)              Vision (product)
+├── Personas            →    Product Personas (extend with specifics)
+├── Jobs                →    Product Jobs (trace back to org jobs)
+├── Beliefs             →    (inherited, never duplicated)
+├── Principles          →    Product Principles (extend, note source)
+└── Non-Goals           →    Product Non-Goals (additive)
+```
+
+### Inheritance Rules
+
+| Component | Rule | Format |
+|-----------|------|--------|
+| **Personas** | Extend with product-specific context | `*Extends: [Org persona] (from manifesto)*` |
+| **Jobs** | Trace back to org-level jobs | Table with Product Job → Org Job columns |
+| **Beliefs** | Inherited automatically | Never include in vision |
+| **Principles** | Add product-specific, note what they extend | `*Extends: "[Org principle]"*` |
+| **Non-Goals** | Additive | Org non-goals apply automatically |
+
+### Example
+
+**Manifesto** (organization):
+```markdown
+## Who We Serve
+- **Agencies & Consultancies**: Teams building solutions for clients
+```
+
+**Vision** (product - architecture tooling):
+```markdown
+## Who This Product Serves
+
+### Flowmade Developers
+
+The team building Flowmade's platform. They need efficient, consistent AI workflows.
+
+*Extends: Agencies & Consultancies (from manifesto) - we are our own first customer.*
+```
+
+The product persona extends the org persona with product-specific context and explicitly notes the connection.
+
+---
+
+## Milestones (Goals)
+
+Milestones are product-level goals that track progress toward the vision.
+
+### Good Milestones
+
+- Specific and measurable
+- Tied to a persona and job to be done
+- Outcome-focused (not activity-focused)
+- Include success criteria in description
+
+```bash
+tea milestones create --title "Automate routine git workflows" \
+  --description "For: Solo developer
+Job: Ship without context switching to git commands
+Success: /commit and /pr commands handle 80% of workflows"
+```
+
+### Milestone-to-Vision Alignment
+
+Every milestone should trace to:
+- A persona (from vision, which extends manifesto)
+- A job to be done (from vision, which traces to manifesto)
+- A measurable outcome
+
+---
+
+## Aligning Issues with Vision
+
+When creating or reviewing issues:
+
+1. **Check persona alignment**: Which persona does this serve?
+2. **Check job alignment**: Which job to be done does this enable?
+3. **Check milestone alignment**: Does this issue support a goal?
+4. **Assign to milestone**: Link the issue to the relevant goal
+
+Every issue should trace back to: "This helps [persona] achieve [job] by [outcome]."
+
+### Identifying Gaps
+
+- **Underserved personas**: Which personas have few milestones/issues?
+- **Unaddressed jobs**: Which jobs to be done have no work toward them?
+- **Empty milestones**: Which milestones have no issues?
+- **Orphan issues**: Issues without a milestone need justification
+
+---
+
+## Continuous Improvement Loop
+
+```
+Manifesto → Vision → Milestones → Issues → Work → Retro → (updates)
+                                                    ↓
+                                          Architecture repo issues
+                                                    ↓
+                                          Encoded into learnings +
+                                          skills/commands/agents
+```
+
+1. **Manifesto** defines organizational identity (very stable)
+2. **Vision** defines product direction, extends manifesto (stable)
+3. **Milestones** define measurable goals (evolve)
+4. **Issues** are work items toward goals
+5. **Work** implements the issues
+6. **Retros** create issues on architecture repo
+7. **Encoding** turns insights into learnings and system improvements
+
+---
+
+## Quick Reference
+
+| Question | Answer |
+|----------|--------|
+| Where do shared personas live? | `manifesto.md` in architecture repo |
+| Where do product personas live? | `vision.md` in product repo (extend org personas) |
+| Where do beliefs live? | `manifesto.md` only (inherited, never duplicated) |
+| Where do goals live? | Gitea milestones (per repo) |
+| What command for org vision? | `/manifesto` |
+| What command for product vision? | `/vision` |
+| What repo for learnings? | Architecture repo |
+| How do product jobs relate to org jobs? | They trace back (show in table) |
+| How do product principles relate? | They extend (note the source) |

tsconfig.json

@@ -1,29 +0,0 @@
-{
-  "compilerOptions": {
-    // Environment setup & latest features
-    "lib": ["ESNext"],
-    "target": "ESNext",
-    "module": "Preserve",
-    "moduleDetection": "force",
-    "jsx": "react-jsx",
-    "allowJs": true,
-
-    // Bundler mode
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "noEmit": true,
-
-    // Best practices
-    "strict": true,
-    "skipLibCheck": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedIndexedAccess": true,
-    "noImplicitOverride": true,
-
-    // Some stricter flags (disabled by default)
-    "noUnusedLocals": false,
-    "noUnusedParameters": false,
-    "noPropertyAccessFromIndexSignature": false
-  }
-}