flowmade-one/architecture
3
0
Fork 0
Code Issues 15 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Migrate from Forgejo to Gitea

Browse Source 
- Replace fj CLI with tea CLI across all commands
- Create new gitea skill, remove forgejo skill
- Update all agents to use gitea skill
- Update commands to use skill-based approach (reference skills instead of embedding CLI commands)
- Update all documentation (README, ARCHITECTURE, VISION, writing guides)
- Swap git remotes: origin now points to git.flowmade.one (Gitea)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Hugo Nijhuis
2025-12-30 13:50:00 +01:00
parent c7025a4c98
commit 68675a7e12
20 changed files with 322 additions and 243 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/writing-agents.md
View File

@@ -78,7 +78,7 @@ Agents gain their expertise by combining multiple skills. Each skill contributes
│ Product Manager Agent │
│ │
│ ┌──────────┐ ┌──────────────┐ │
│ │ forgejo │ │issue-writing │ │
│ │ gitea │ │issue-writing │ │
│ │ │ │ │ │
│ │ CLI │ │ Structure │ │
│ │ commands │ │ patterns │ │
@@ -95,7 +95,7 @@ Agents gain their expertise by combining multiple skills. Each skill contributes
```
The agent can:
- Use **forgejo** to interact with issues and PRs
- 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
@@ -106,9 +106,9 @@ When skills combine, new capabilities emerge:
| Skills Combined | Emergent Capability |
|-----------------|---------------------|
| forgejo + issue-writing | Create well-structured issues programmatically |
| gitea + issue-writing | Create well-structured issues programmatically |
| backlog-grooming + issue-writing | Improve existing issues systematically |
| roadmap-planning + forgejo | Plan and create linked issue hierarchies |
| roadmap-planning + gitea | Plan and create linked issue hierarchies |
| All four skills | Full backlog management lifecycle |
## Use Cases for Agents
@@ -225,7 +225,7 @@ Command spawns product-manager agent
|----------|--------|--------|
| Create one issue | No | Single skill, simple task |
| Review 20 issues | Yes | Batch processing, isolation |
| Quick CLI lookup | No | Just need forgejo reference |
| 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 |
@@ -245,14 +245,14 @@ Specialized agent for backlog management and roadmap planning.
```markdown
## Skills
- forgejo
- 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 (forgejo)
- Reading/writing issues (gitea)
- Creating quality content (issue-writing)
- Evaluating existing issues (backlog-grooming)
- Planning work strategically (roadmap-planning)
@@ -270,7 +270,7 @@ This agent can:
**Capabilities section** tells spawners what to expect. Each capability maps to skill combinations:
- "Review and improve" = backlog-grooming + issue-writing
- "Create new issues" = forgejo + issue-writing
- "Create new issues" = gitea + issue-writing
- "Analyze backlog" = backlog-grooming + roadmap-planning
- "Plan breakdowns" = roadmap-planning + issue-writing
@@ -296,7 +296,7 @@ Spawn this agent for:
- Always fetches current issue state before making changes
- Asks for approval before creating or modifying issues
- Provides clear summaries of actions taken
- Uses the fj CLI for all Forgejo operations
- Uses the tea CLI for all Forgejo operations
```
**Behavior section** sets operational rules. These ensure:
@@ -368,7 +368,7 @@ These examples show recommended model configurations for different agent types:
---
name: code-reviewer
model: sonnet
skills: forgejo, code-review
skills: gitea, code-review
---
```
Code review requires understanding code patterns and conventions but rarely needs the deepest reasoning. Sonnet provides good balance.
@@ -421,7 +421,7 @@ Include only skills the agent needs. More skills = more context = potential conf
**Too many skills:**
```markdown
## Skills
- forgejo
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
@@ -434,7 +434,7 @@ Include only skills the agent needs. More skills = more context = potential conf
**Right-sized:**
```markdown
## Skills
- forgejo
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning

108
docs/writing-commands.md
View File

@@ -66,19 +66,21 @@ The body contains the workflow steps that Claude follows when the command is inv
```markdown
---
description: Work on a Forgejo issue. Fetches issue details and sets up branch.
description: Work on a Gitea issue. Fetches issue details and sets up branch.
argument-hint: <issue-number>
---
# Work on Issue #$1
1. **View the issue**: `fj issue view $1`
Use the gitea skill.
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**: `git push -u origin <branch>`
7. **Create PR**: `fj pr create "[Issue #$1] <title>" --body "Closes #$1"`
6. **Push** the branch to origin
7. **Create PR** with title "[Issue #$1] <title>" and body "Closes #$1"
```
## Argument Handling
@@ -95,13 +97,13 @@ When users invoke a command with arguments:
The system provides the arguments via the `$1`, `$2`, etc. placeholders in the command body:
```markdown
# Work on Issue #$1
1. **View the issue**: `fj issue view $1`
1. **View the issue** to understand requirements
```
Becomes:
```markdown
# Work on Issue #42
1. **View the issue**: `fj issue view 42`
1. **View the issue** to understand requirements
```
### Argument Hints
@@ -136,13 +138,15 @@ argument-hint: [issue-number]
# Groom Issues
Use the gitea skill.
## If issue number provided ($1):
1. **Fetch the issue**: `fj issue view $1`
1. **Fetch the issue** details
2. **Evaluate** against checklist
...
## If no argument (groom all):
1. **List open issues**: `fj issue search -s open`
1. **List open issues**
2. **Review each** against checklist
...
```
@@ -159,8 +163,10 @@ argument-hint: [title] or "batch"
# Create Issue(s)
Use the gitea skill.
## Single Issue (default)
If title provided: `fj issue create "$1" --body "<description>"`
If title provided, create an issue with that title.
## Batch Mode
If $1 is "batch":
@@ -179,24 +185,24 @@ Commands reference skills by name to gain domain knowledge. When a skill is refe
```markdown
# Groom Issues
Use the **backlog-grooming** and **issue-writing** skills.
Use the **gitea**, **backlog-grooming**, and **issue-writing** skills.
1. **Fetch the issue**: `fj issue view $1`
1. **Fetch the issue** details
2. **Evaluate** against grooming checklist
...
```
The phrase "Use the backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from both skill files.
The phrase "Use the gitea, backlog-grooming and issue-writing skills" tells Claude to read and apply knowledge from those skill files.
### Implicit Reference
### Skill-Based Approach
Skills can also be used implicitly via tool references:
Commands should reference skills rather than embedding CLI commands directly:
```markdown
1. **View the issue**: `fj issue view $1`
1. **Fetch the issue** details
```
This implicitly uses knowledge from the `forgejo` skill (knowing the `fj` command syntax).
This relies on the `gitea` skill to provide the CLI knowledge.
### When to Reference Skills
@@ -247,7 +253,7 @@ Always ask for approval before significant actions:
```markdown
5. **Ask for approval** before creating issues
6. **Create issues** in order using `fj issue create`
6. **Create issues** in order
```
Common approval points:
@@ -261,9 +267,9 @@ When the command leads to multiple possible actions:
```markdown
Ask the user what action to take:
- **Merge**: `fj pr merge $1` - Approve and merge the PR
- **Request changes**: `fj pr comment $1 "<feedback>"` - Leave feedback
- **Comment only**: `fj pr comment $1 "<comment>"` - Add a comment
- **Merge**: Approve and merge the PR
- **Request changes**: Leave feedback without merging
- **Comment only**: Add a comment for discussion
```
### Gathering Input
@@ -301,27 +307,29 @@ Let's examine existing commands to understand effective patterns.
```markdown
---
description: Work on a Forgejo issue. Fetches issue details and sets up branch.
description: Work on a Gitea issue. Fetches issue details and sets up branch.
argument-hint: <issue-number>
---
# Work on Issue #$1
1. **View the issue**: `fj issue view $1`
Use the gitea skill.
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**: `git push -u origin <branch>`
7. **Create PR**: `fj pr create "[Issue #$1] <title>" --body "Closes #$1"`
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
- **Tool integration**: Git and fj commands specified
- **No explicit skill reference**: Uses forgejo knowledge implicitly
- **Skill reference**: Uses gitea skill for CLI knowledge
- **Git integration**: Branch and push steps specified
### Example 2: dashboard (No Arguments)
@@ -332,10 +340,11 @@ description: Show dashboard of open issues, PRs awaiting review, and CI status.
# Repository Dashboard
Run these commands and present a summary:
Use the gitea skill.
1. **Open Issues**: `fj issue search -s open`
2. **Open PRs**: `fj pr search -s open`
Fetch and display:
1. All open issues
2. All open PRs
Format as tables showing issue/PR number, title, and author.
```
@@ -356,20 +365,20 @@ argument-hint: [issue-number]
# Groom Issues
Use the backlog-grooming and issue-writing skills.
Use the gitea, backlog-grooming, and issue-writing skills.
## If issue number provided ($1):
1. **Fetch the issue**: `fj issue view $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: `fj issue edit $1 --body "..."`
5. **Update issue** if approved
## If no argument (groom all):
1. **List open issues**: `fj issue search -s open`
1. **List open issues**
2. **Review each** against grooming checklist
3. **Categorize**: Ready / Needs work / Stale
4. **Present summary** table
@@ -379,7 +388,7 @@ Use the backlog-grooming and issue-writing skills.
**Key patterns:**
- **Optional argument**: `[issue-number]` with brackets
- **Mode switching**: Different behavior based on argument presence
- **Explicit skill reference**: "Use the backlog-grooming and issue-writing skills"
- **Explicit skill reference**: "Use the gitea, backlog-grooming and issue-writing skills"
- **Approval workflow**: "Ask user if they want to apply changes"
- **Categorization**: Groups items for presentation
@@ -393,7 +402,7 @@ argument-hint: <feature-description>
# Plan Feature: $1
Use the roadmap-planning, issue-writing, and forgejo skills.
Use the gitea, roadmap-planning, and issue-writing skills.
1. **Understand the feature**: Analyze what "$1" involves
2. **Explore the codebase** if needed to understand context
@@ -407,7 +416,7 @@ Use the roadmap-planning, issue-writing, and forgejo skills.
...
```
5. **Ask for approval** before creating issues
6. **Create issues** in order using `fj issue create`
6. **Create issues** in order
7. **Update dependencies** with actual issue numbers
8. **Present summary** with links to created issues
```
@@ -423,15 +432,16 @@ Use the roadmap-planning, issue-writing, and forgejo skills.
```markdown
---
description: Review a Forgejo pull request. Fetches PR details, diff, and comments.
description: Review a Gitea pull request. Fetches PR details, diff, and comments.
argument-hint: <pr-number>
---
# Review PR #$1
1. **View PR details**: `fj pr view $1`
2. **Check status**: `fj pr status $1`
3. **Get the diff**: `fj pr view $1 diff`
Use the gitea skill.
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
@@ -440,13 +450,13 @@ Review the changes and provide feedback on:
- Documentation
Ask the user what action to take:
- **Merge**: `fj pr merge $1` - Approve and merge the PR
- **Request changes**: `fj pr comment $1 "<feedback>"` - Leave feedback
- **Comment only**: `fj pr comment $1 "<comment>"` - Add a comment
- **Merge**: Approve and merge the PR
- **Request changes**: Leave feedback without merging
- **Comment only**: Add a comment for discussion
```
**Key patterns:**
- **Information gathering**: Multiple commands to get context
- **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
@@ -497,7 +507,7 @@ Each step should be unambiguous:
**Clear:**
```markdown
1. **View the issue**: `fj issue view $1`
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
```
@@ -513,9 +523,7 @@ List the open issues.
**Showing:**
```markdown
**Open Issues**: `fj issue search -s open`
Format as table:
Fetch all open issues and format as table:
| # | Title | Author |
|---|-------|--------|
```
@@ -526,7 +534,7 @@ Never modify resources without user approval:
```markdown
4. **Present plan** for approval
5. **If approved**, create issues using `fj issue create`
5. **If approved**, create the issues
```
### 4. Handle Edge Cases
@@ -535,7 +543,7 @@ Consider what happens when things are empty or unexpected:
```markdown
## If no argument (groom all):
1. **List open issues**: `fj issue search -s open`
1. **List open issues**
2. If no issues found, report "No open issues to groom"
3. Otherwise, **review each** against checklist
```

22
docs/writing-skills.md
View File

@@ -14,7 +14,7 @@ Skills live in the `skills/` directory, each in its own folder:
```
skills/
├── forgejo/
├── gitea/
│ └── SKILL.md
├── issue-writing/
│ └── SKILL.md
@@ -75,7 +75,7 @@ Document pitfalls to avoid.
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 `forgejo`).
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 Loaded
@@ -103,7 +103,7 @@ Agents list their skills explicitly:
# Product Manager Agent
## Skills
- forgejo
- gitea
- issue-writing
- backlog-grooming
- roadmap-planning
@@ -121,7 +121,7 @@ Skills can mention other skills for related knowledge:
...
When creating issues, follow the patterns in the **issue-writing** skill.
Use **forgejo** commands to create the issues.
Use **gitea** commands to create the issues.
```
This creates a natural knowledge hierarchy without duplicating content.
@@ -136,7 +136,7 @@ This creates a natural knowledge hierarchy without duplicating content.
- Avoid generic names: `utils`, `helpers`, `common`
Good names:
- `forgejo` - Tool-specific knowledge
- `gitea` - Tool-specific knowledge
- `issue-writing` - Activity-focused
- `backlog-grooming` - Process-focused
- `roadmap-planning` - Task-focused
@@ -147,7 +147,7 @@ The H1 title in `SKILL.md` should match the folder name in Title Case:
| Folder | Title |
|--------|-------|
| `forgejo` | Forgejo CLI (fj) |
| `gitea` | Forgejo CLI (fj) |
| `issue-writing` | Issue Writing |
| `backlog-grooming` | Backlog Grooming |
| `roadmap-planning` | Roadmap Planning |
@@ -266,9 +266,9 @@ Skills should reflect current practices. When workflows change:
Let's examine the existing skills to understand effective patterns.
### Example 1: forgejo (Tool Reference)
### Example 1: gitea (Tool Reference)
The `forgejo` skill is a **tool reference**—it documents how to use a specific CLI tool.
The `gitea` skill is a **tool reference**—it documents how to use a specific CLI tool.
```markdown
# Forgejo CLI (fj)
@@ -276,15 +276,15 @@ The `forgejo` skill is a **tool reference**—it documents how to use a specific
Command-line interface for interacting with Forgejo repositories.
## Authentication
The `fj` CLI authenticates via `fj auth login`. Credentials are stored locally.
The `tea` CLI authenticates via `tea auth login`. Credentials are stored locally.
## Common Commands
### Issues
\```bash
# List issues
fj issue search -s open # Open issues
fj issue search -s closed # Closed issues
tea issue search -s open # Open issues
tea issue search -s closed # Closed issues
...
\```
```