Consider renaming repo to 'architecture' to include engineering patterns #37

New Issue

HugoNijhuis · 2026-01-07T15:28:03Z

HugoNijhuis commented

2026-01-07 15:28:03 +00:00

Context

The /retro command captures learnings from completed work, but these learnings often go beyond AI workflow improvements - they include general engineering patterns like:

Data migration strategies
Verification patterns (confirm new system works before cleaning up old)
Other software architecture practices

Problem

Currently this repo is named ai and focused on Claude Code setup (commands, skills, agents). But:

Engineering patterns have no natural home
We want Claude to learn from these patterns when doing future work
The patterns should be part of the "how we work" knowledge base

Proposal

Rename repo from ai to architecture to encompass:

architecture/
├── commands/           # AI workflow entry points
├── skills/             # Tool-specific knowledge (gitea, etc.)
├── agents/             # Subtask handlers
├── patterns/           # Engineering patterns (migrations, verification, etc.)
├── scripts/            # Hooks, setup
├── settings.json       # Claude config
├── Makefile            # make install → ~/.claude/
└── CLAUDE.md           # High-level principles

The name "architecture" covers both:

Architecture of our AI workflow - commands, skills, agents
Architecture of our software - patterns, practices

Key insight

"Setting up AI" isn't just mechanical config - it includes teaching Claude our engineering practices. The patterns become knowledge that Claude uses on future work via @~/.claude/patterns/xxx.md references.

Questions to resolve

Is architecture the right name? Alternatives: engineering, practices, workflow
How should patterns be organized? By category (migrations, testing) or by project?
Should patterns be referenced like skills, or loaded differently?

## Context The `/retro` command captures learnings from completed work, but these learnings often go beyond AI workflow improvements - they include general engineering patterns like: - Data migration strategies - Verification patterns (confirm new system works before cleaning up old) - Other software architecture practices ## Problem Currently this repo is named `ai` and focused on Claude Code setup (commands, skills, agents). But: 1. Engineering patterns have no natural home 2. We want Claude to learn from these patterns when doing future work 3. The patterns should be part of the "how we work" knowledge base ## Proposal Rename repo from `ai` to `architecture` to encompass: ``` architecture/ ├── commands/ # AI workflow entry points ├── skills/ # Tool-specific knowledge (gitea, etc.) ├── agents/ # Subtask handlers ├── patterns/ # Engineering patterns (migrations, verification, etc.) ├── scripts/ # Hooks, setup ├── settings.json # Claude config ├── Makefile # make install → ~/.claude/ └── CLAUDE.md # High-level principles ``` The name "architecture" covers both: 1. **Architecture of our AI workflow** - commands, skills, agents 2. **Architecture of our software** - patterns, practices ## Key insight "Setting up AI" isn't just mechanical config - it includes teaching Claude our engineering practices. The patterns become knowledge that Claude uses on future work via `@~/.claude/patterns/xxx.md` references. ## Questions to resolve - Is `architecture` the right name? Alternatives: `engineering`, `practices`, `workflow` - How should patterns be organized? By category (migrations, testing) or by project? - Should patterns be referenced like skills, or loaded differently?

HugoNijhuis commented

2026-01-07 18:52:51 +00:00

Implementation plan created. See issues #38-#44 for the breakdown:

#38 Create manifesto.md for organization vision
#39 Create learnings/ folder with structure and template
#40 Create /manifesto command
#41 Update /vision command for product-level only
#42 Update /retro command to store learnings
#43 Update vision-management skill
#44 Rename repo from 'ai' to 'architecture'

Dependency order:

#38 (manifesto) and #39 (learnings) can be done in parallel
#40, #41 depend on Create manifesto.md for organization vision (#38)
#42 depends on Create learnings/ folder with structure and template (#39)
#43 can be done after understanding manifesto/vision split
#44 (rename) is last, depends on all others

Implementation plan created. See issues #38-#44 for the breakdown: - #38 Create manifesto.md for organization vision - #39 Create learnings/ folder with structure and template - #40 Create /manifesto command - #41 Update /vision command for product-level only - #42 Update /retro command to store learnings - #43 Update vision-management skill - #44 Rename repo from 'ai' to 'architecture' Dependency order: 1. #38 (manifesto) and #39 (learnings) can be done in parallel 2. #40, #41 depend on #38 3. #42 depends on #39 4. #43 can be done after understanding manifesto/vision split 5. #44 (rename) is last, depends on all others

HugoNijhuis commented

2026-01-07 20:04:35 +00:00

Completed

This has been fully implemented via issues #38-#44:

What was implemented

Repo renamed from ai to architecture (#44)
Organization-level identity via manifesto.md (#38):
- Who We Are, Who We Serve (personas)
- What They're Trying to Achieve (jobs to be done)
- What We Believe, Guiding Principles, Non-Goals
Learnings system via learnings/ folder (#39):
- Captures insights from retros
- Issues created on architecture repo
- Later encoded into skills/commands/agents
Vision structure clarified (#40, #41, #43):
- /manifesto command for organization-level
- /vision command for product-level
- Updated vision-management skill with inheritance model
Retro flow simplified (#42):
- Retro → Issue (architecture repo) → Later encode

Key insight realized

Instead of a patterns/ folder, we use learnings/ that get encoded into skills/commands/agents - making the knowledge active rather than passive.

## Completed This has been fully implemented via issues #38-#44: ### What was implemented 1. **Repo renamed** from `ai` to `architecture` (#44) 2. **Organization-level identity** via `manifesto.md` (#38): - Who We Are, Who We Serve (personas) - What They're Trying to Achieve (jobs to be done) - What We Believe, Guiding Principles, Non-Goals 3. **Learnings system** via `learnings/` folder (#39): - Captures insights from retros - Issues created on architecture repo - Later encoded into skills/commands/agents 4. **Vision structure clarified** (#40, #41, #43): - `/manifesto` command for organization-level - `/vision` command for product-level - Updated vision-management skill with inheritance model 5. **Retro flow simplified** (#42): - Retro → Issue (architecture repo) → Later encode ### Key insight realized Instead of a `patterns/` folder, we use `learnings/` that get encoded into skills/commands/agents - making the knowledge active rather than passive.

HugoNijhuis closed this issue

2026-01-07 20:04:41 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: flowmade-one/architecture#37