chore: move documentation files to old2 folder
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
426
old2/ARCHITECTURE.md
Normal file
426
old2/ARCHITECTURE.md
Normal file
@@ -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
|
||||
103
old2/CLAUDE.md
Normal file
103
old2/CLAUDE.md
Normal file
@@ -0,0 +1,103 @@
|
||||
# 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 |
|
||||
| `software-architecture.md` | Architectural patterns (human docs, mirrored in skill) |
|
||||
| `learnings/` | Historical record and governance |
|
||||
| `skills/` | AI workflows and knowledge modules |
|
||||
| `agents/` | Focused subtask handlers |
|
||||
| `settings.json` | Claude Code configuration |
|
||||
| `Makefile` | Install symlinks to ~/.claude/ |
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
architecture/
|
||||
├── manifesto.md # Organization vision and beliefs
|
||||
├── software-architecture.md # Patterns linked to beliefs (DDD, ES)
|
||||
├── learnings/ # Captured learnings and governance
|
||||
├── skills/ # User-invocable (/work-issue) and background skills
|
||||
├── 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 | Skill | 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 Skills
|
||||
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| `/vision-to-backlog [vision-file]` | Transform product vision into executable backlog via DDD |
|
||||
| `/create-milestones` | Organize issues into value-based milestones |
|
||||
| `/spawn-issues <n> [<n>...]` | Implement multiple issues in parallel with automated review |
|
||||
| `/spawn-pr-reviews <n> [<n>...]` | Review one or more PRs using code-reviewer agents |
|
||||
| `/spawn-pr-fixers <n> [<n>...]` | Fix one or more PRs based on review feedback |
|
||||
| `/create-capability` | Create new skill, agent, or capability for the architecture |
|
||||
| `/capability-writing` | Guide for designing capabilities following best practices |
|
||||
|
||||
## 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
|
||||
|
||||
Skills come in two types:
|
||||
|
||||
**User-invocable** (`user-invocable: true`): Workflows users trigger with `/skill-name`
|
||||
- **Purpose**: Orchestrate workflows with user interaction
|
||||
- **Location**: `skills/<name>/SKILL.md`
|
||||
- **Usage**: User types `/dashboard`, `/work-issue 42`, etc.
|
||||
|
||||
**Background** (`user-invocable: false`): Knowledge auto-loaded when needed
|
||||
- **Purpose**: Encode best practices and tool knowledge
|
||||
- **Location**: `skills/<name>/SKILL.md`
|
||||
- **Usage**: Referenced by other skills via `@~/.claude/skills/xxx/SKILL.md`
|
||||
|
||||
### 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/agents.
|
||||
|
||||
- **Purpose**: Historical record + governance + continuous improvement
|
||||
- **Location**: `learnings/YYYY-MM-DD-title.md`
|
||||
- **Flow**: Retro → Issue → Encode into learning + system update
|
||||
183
old2/README.md
Normal file
183
old2/README.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# Architecture
|
||||
|
||||
The organizational source of truth: how we work, who we serve, what we believe, and how we build software with AI.
|
||||
|
||||
A composable toolkit for enhancing [Claude Code](https://claude.ai/claude-code) with structured workflows, issue management, and AI-assisted development practices.
|
||||
|
||||
## 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
|
||||
|
||||
The project is built around three composable component types:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ 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
|
||||
# Clone the repository
|
||||
git clone ssh://git@code.flowmade.one/flowmade-one/architecture.git
|
||||
cd architecture
|
||||
|
||||
# Install symlinks to ~/.claude/
|
||||
make install
|
||||
```
|
||||
|
||||
### Forgejo Setup
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
## Available Commands
|
||||
|
||||
| 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/
|
||||
├── 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
|
||||
```
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Working on an Issue
|
||||
|
||||
```
|
||||
> /work-issue 42
|
||||
|
||||
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...
|
||||
```
|
||||
|
||||
### Planning a Feature
|
||||
|
||||
```
|
||||
> /plan-issues Add dark mode support
|
||||
|
||||
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
|
||||
|
||||
Create these issues? [y/n]
|
||||
```
|
||||
|
||||
### Daily Standup
|
||||
|
||||
```
|
||||
> /dashboard
|
||||
|
||||
Open Issues (3):
|
||||
| # | Title | Labels |
|
||||
|----|--------------------------|-------------|
|
||||
| 42 | Add user authentication | feature |
|
||||
| 38 | Fix login redirect | bug |
|
||||
| 35 | Update dependencies | maintenance |
|
||||
|
||||
Open PRs (1):
|
||||
| # | Title | Status |
|
||||
|----|--------------------------|-------------|
|
||||
| 41 | Add password reset flow | review |
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The `settings.json` configures Claude Code behavior:
|
||||
|
||||
- **Model selection**: Uses Opus for complex tasks
|
||||
- **Status line**: Shows git branch and status
|
||||
- **Hooks**: Pre-commit validation for secrets and YAML
|
||||
|
||||
## Uninstall
|
||||
|
||||
```bash
|
||||
make uninstall
|
||||
```
|
||||
|
||||
This removes symlinks from `~/.claude/` and restores any backed-up files.
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
95
old2/VISION.md
Normal file
95
old2/VISION.md
Normal file
@@ -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.
|
||||
108
old2/manifesto.md
Normal file
108
old2/manifesto.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# 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.
|
||||
|
||||
### Architecture Beliefs
|
||||
|
||||
We believe certain outcomes matter more than others when building systems:
|
||||
|
||||
- **Auditability by default.** Systems should remember what happened, not just current state. History is valuable - for debugging, compliance, understanding, and recovery.
|
||||
|
||||
- **Business language in code.** The words domain experts use should appear in the codebase. When code mirrors how the business thinks, everyone can reason about it.
|
||||
|
||||
- **Independent evolution.** Parts of the system should change without breaking other parts. Loose coupling isn't just nice - it's how small teams stay fast as systems grow.
|
||||
|
||||
- **Explicit over implicit.** Intent should be visible. Side effects should be traceable. When something important happens, the system should make that obvious.
|
||||
|
||||
See [software-architecture.md](./software-architecture.md) for the patterns we use to achieve these outcomes.
|
||||
|
||||
### Quality Without Ceremony
|
||||
|
||||
- Ship small, ship often
|
||||
- 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.
|
||||
71
old2/repos.md
Normal file
71
old2/repos.md
Normal file
@@ -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
|
||||
130
old2/software-architecture.md
Normal file
130
old2/software-architecture.md
Normal file
@@ -0,0 +1,130 @@
|
||||
# Software Architecture
|
||||
|
||||
> **For Claude:** This content is mirrored in `skills/software-architecture/SKILL.md` which is auto-triggered when relevant. You don't need to load this file directly.
|
||||
|
||||
This document describes the architectural patterns we use to achieve our [architecture beliefs](./manifesto.md#architecture-beliefs). It serves as human-readable organizational documentation.
|
||||
|
||||
## Beliefs to Patterns
|
||||
|
||||
| Belief | Primary Pattern | Supporting Patterns |
|
||||
|--------|-----------------|---------------------|
|
||||
| Auditability by default | Event Sourcing | Immutable events, temporal queries |
|
||||
| Business language in code | Domain-Driven Design | Ubiquitous language, aggregates, bounded contexts |
|
||||
| Independent evolution | Event-driven communication | Bounded contexts, published language |
|
||||
| Explicit over implicit | Commands and Events | Domain events, clear intent |
|
||||
|
||||
## Event Sourcing
|
||||
|
||||
**Achieves:** Auditability by default
|
||||
|
||||
Instead of storing current state, we store the sequence of events that led to it.
|
||||
|
||||
**Core concepts:**
|
||||
- **Events** are immutable facts about what happened, named in past tense: `OrderPlaced`, `PaymentReceived`
|
||||
- **State** is derived by replaying events, not stored directly
|
||||
- **Event store** is append-only - history is never modified
|
||||
|
||||
**Why this matters:**
|
||||
- Complete audit trail for free
|
||||
- Debug by replaying history
|
||||
- Answer "what was the state at time X?"
|
||||
- Recover from bugs by fixing logic and replaying
|
||||
|
||||
**Trade-offs:**
|
||||
- More complex than CRUD for simple cases
|
||||
- Requires thinking in events, not state
|
||||
- Eventually consistent read models
|
||||
|
||||
## Domain-Driven Design
|
||||
|
||||
**Achieves:** Business language in code
|
||||
|
||||
The domain model reflects how the business thinks and talks.
|
||||
|
||||
**Core concepts:**
|
||||
- **Ubiquitous language** - same terms in code, conversations, and documentation
|
||||
- **Bounded contexts** - explicit boundaries where terms have consistent meaning
|
||||
- **Aggregates** - clusters of objects that change together, with one root entity
|
||||
- **Domain events** - capture what happened in business terms
|
||||
|
||||
**Why this matters:**
|
||||
- Domain experts can read and validate the model
|
||||
- New team members learn the domain through code
|
||||
- Changes in business rules map clearly to code changes
|
||||
|
||||
**Trade-offs:**
|
||||
- Upfront investment in understanding the domain
|
||||
- Boundaries may need to shift as understanding grows
|
||||
- Overkill for pure technical/infrastructure code
|
||||
|
||||
## Event-Driven Communication
|
||||
|
||||
**Achieves:** Independent evolution
|
||||
|
||||
Services communicate by publishing events, not calling each other directly.
|
||||
|
||||
**Core concepts:**
|
||||
- **Publish events** when something important happens
|
||||
- **Subscribe to events** you care about
|
||||
- **No direct dependencies** between publisher and subscriber
|
||||
- **Eventual consistency** - accept that not everything updates instantly
|
||||
|
||||
**Why this matters:**
|
||||
- Add new services without changing existing ones
|
||||
- Services can be deployed independently
|
||||
- Natural resilience - if a subscriber is down, events queue
|
||||
|
||||
**Trade-offs:**
|
||||
- Harder to trace request flow
|
||||
- Eventual consistency requires different thinking
|
||||
- Need infrastructure for reliable event delivery
|
||||
|
||||
## Commands and Events
|
||||
|
||||
**Achieves:** Explicit over implicit
|
||||
|
||||
Distinguish between requests (commands) and facts (events).
|
||||
|
||||
**Core concepts:**
|
||||
- **Commands** express intent: `PlaceOrder`, `CancelSubscription`
|
||||
- Commands can be rejected (validation, business rules)
|
||||
- **Events** express facts: `OrderPlaced`, `SubscriptionCancelled`
|
||||
- Events are immutable - what happened, happened
|
||||
|
||||
**Why this matters:**
|
||||
- Clear separation of "trying to do X" vs "X happened"
|
||||
- Commands validate, events just record
|
||||
- Enables replay - reprocess events with new logic
|
||||
|
||||
## When to Diverge
|
||||
|
||||
These patterns are defaults, not mandates. Diverge intentionally when:
|
||||
|
||||
- **Simplicity wins** - a simple CRUD endpoint doesn't need event sourcing
|
||||
- **Performance requires it** - sometimes synchronous calls are necessary
|
||||
- **Team context** - patterns the team doesn't understand cause more harm than good
|
||||
- **Prototyping** - validate ideas before investing in full architecture
|
||||
|
||||
When diverging, document the decision in the project's vision.md (see below).
|
||||
|
||||
## Project-Level Architecture
|
||||
|
||||
Each project should document its architectural choices in `vision.md` under an **Architecture** section:
|
||||
|
||||
```markdown
|
||||
## Architecture
|
||||
|
||||
This project follows organization architecture patterns.
|
||||
|
||||
### Alignment
|
||||
- Event sourcing for [which aggregates/domains]
|
||||
- Bounded contexts: [list contexts and their responsibilities]
|
||||
- Event-driven communication between [which services]
|
||||
|
||||
### Intentional Divergences
|
||||
| Area | Standard Pattern | What We Do Instead | Why |
|
||||
|------|------------------|-------------------|-----|
|
||||
| [area] | [expected pattern] | [actual approach] | [reasoning] |
|
||||
```
|
||||
|
||||
This creates traceability: org beliefs → patterns → project decisions.
|
||||
Reference in New Issue
Block a user