diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 4172bea..503bd0d 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -23,7 +23,7 @@ The architecture follows a layered composition model where each component type s │ │ AGENTS │ │ SKILLS │ │ │ │ Specialized │ │ Knowledge modules │ │ │ │ subagents │ │ │ │ -│ │ │ │ issue-writing forgejo │ │ +│ │ │ │ issue-writing gitea │ │ │ │ product-manager │ │ backlog-grooming roadmap-planning │ │ │ └─────────────────┘ └─────────────────────────────────────┘ │ │ │ ▲ │ @@ -49,13 +49,13 @@ Each command file contains: ```yaml --- -description: Work on a Forgejo issue +description: Work on a Gitea issue argument-hint: --- # Work on Issue #$1 -1. **View the issue**: `fj issue view $1` +1. **View the issue**: `tea issue view $1` 2. **Create a branch**: `git checkout -b issue-$1-` ... ``` @@ -79,13 +79,13 @@ Create a command when you have: | Command | Purpose | Skills Used | |---------|---------|-------------| -| `/work-issue` | Implement an issue end-to-end | forgejo | -| `/dashboard` | View open issues and PRs | forgejo | -| `/review-pr` | Review and act on a PR | forgejo | -| `/create-issue` | Create single or batch issues | forgejo, issue-writing | +| `/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 | forgejo, roadmap-planning | -| `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, forgejo | +| `/roadmap` | View issues organized by status | gitea, roadmap-planning | +| `/plan-issues` | Break down features into issues | roadmap-planning, issue-writing, gitea | --- @@ -134,7 +134,7 @@ Create a skill when you find yourself: | Skill | Purpose | |-------|---------| -| `forgejo` | How to use the Forgejo CLI for issues and PRs | +| `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 | @@ -204,8 +204,8 @@ Create an agent when you need: | Agent | Skills | Use Case | |-------|--------|----------| -| `product-manager` | forgejo, issue-writing, backlog-grooming, roadmap-planning | Batch issue operations, backlog reviews, feature planning | -| `code-reviewer` | forgejo, code-review | Automated PR review, quality checks | +| `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 | --- @@ -222,7 +222,7 @@ User invokes command │ workflow steps │ └───────────────────┘ │ - ├─── Direct action (git, fj CLI) + ├─── Direct action (git, tea CLI) │ ├─── Reference skill for knowledge │ │ @@ -253,7 +253,7 @@ User invokes command 2. **Skills consulted**: - `roadmap-planning`: How to break down features - `issue-writing`: How to structure each issue - - `forgejo`: How to create issues via CLI + - `gitea`: How to create issues via CLI 3. **Workflow executed**: - Analyze what "dark mode" involves @@ -304,7 +304,7 @@ Agents declare their skills in the YAML frontmatter: ```yaml --- name: product-manager -skills: forgejo, issue-writing, backlog-grooming +skills: gitea, issue-writing, backlog-grooming --- ``` @@ -335,7 +335,7 @@ The agent works autonomously and returns results to the command. Small, focused components combine to handle complex scenarios: ``` -/plan-issues = roadmap-planning + issue-writing + forgejo +/plan-issues = roadmap-planning + issue-writing + gitea product-manager = all four skills combined ``` @@ -368,7 +368,7 @@ ai/ │ ├── roadmap.md │ └── plan-issues.md ├── skills/ # Knowledge modules -│ ├── forgejo/ +│ ├── gitea/ │ │ └── SKILL.md │ ├── issue-writing/ │ │ └── SKILL.md diff --git a/CLAUDE.md b/CLAUDE.md index 85f3e3c..8f346b8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -25,16 +25,16 @@ ai/ All files symlink to `~/.claude/` via `make install`. -## Forgejo Integration +## Gitea Integration -Uses `fj` CLI (forgejo-cli) for issue/PR management: +Uses `tea` CLI for issue/PR management: ```bash # Setup (one-time) -brew install forgejo-cli -echo "YOUR_TOKEN" | fj -H code.flowmade.one auth add-key username +brew install tea +tea logins add --name flowmade --url https://git.flowmade.one --token <your-token> -# Token needs scopes: read:user, read:repository, write:issue, write:repository +# Create token at: https://git.flowmade.one/user/settings/applications ``` ### Available Commands diff --git a/README.md b/README.md index 62d7e47..8d604db 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ The project is built around three composable component types: │ │ ┌───────────────────────────────────────────┐ │ │ │ │ │ SKILLS │ │ │ │ │ │ Reusable knowledge modules │ │ │ -│ │ │ (forgejo, issue-writing, planning) │ │ │ +│ │ │ (gitea, issue-writing, planning) │ │ │ │ │ └───────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘ @@ -47,7 +47,7 @@ The project is built around three composable component types: ### Prerequisites - [Claude Code CLI](https://claude.ai/claude-code) installed -- [Forgejo CLI](https://code.forgejo.org/forgejo/forgejo-cli) (`fj`) for issue/PR management +- [Forgejo CLI](https://code.gitea.org/gitea/gitea-cli) (`tea`) for issue/PR management ### Installation @@ -63,11 +63,11 @@ make install ### Forgejo Setup ```bash -# Install forgejo-cli -brew install forgejo-cli +# Install gitea-cli +brew install gitea-cli # Authenticate (one-time) -echo "YOUR_TOKEN" | fj -H code.flowmade.one auth add-key username +echo "YOUR_TOKEN" | tea -H code.flowmade.one auth add-key username # Required token scopes: read:user, read:repository, write:issue, write:repository ``` @@ -97,7 +97,7 @@ ai/ │ ├── groom.md │ └── roadmap.md ├── skills/ # Reusable knowledge modules -│ ├── forgejo/ # Forgejo CLI integration +│ ├── gitea/ # Forgejo CLI integration │ ├── issue-writing/ # Issue structure best practices │ ├── backlog-grooming/ # Backlog maintenance │ ├── roadmap-planning/ # Feature breakdown diff --git a/VISION.md b/VISION.md index 01739a6..0a71bf8 100644 --- a/VISION.md +++ b/VISION.md @@ -29,7 +29,7 @@ Skills are knowledge modules—focused documents that teach Claude how to do som Examples: - `issue-writing`: How to structure clear, actionable issues -- `forgejo`: How to use the Forgejo CLI for issue/PR management +- `gitea`: How to use the Gitea CLI for issue/PR management - `backlog-grooming`: What makes a healthy backlog Skills don't do anything on their own. They're building blocks. @@ -63,11 +63,11 @@ This toolkit is for: - **Developers using Claude Code** who want consistent, efficient workflows - **Teams** who want to encode and share their best practices -- **Forgejo/Git users** who want seamless issue and PR management integrated into their AI workflow +- **Gitea/Git users** who want seamless issue and PR management integrated into their AI workflow You should have: - Claude Code CLI installed -- A Forgejo instance (or adapt the tooling for GitHub/GitLab) +- A Gitea instance (or adapt the tooling for GitHub/GitLab) - Interest in treating AI assistance as a structured tool, not just a chat interface ## Guiding Principles diff --git a/agents/code-reviewer/AGENT.md b/agents/code-reviewer/AGENT.md index 7d5ffd3..b931eba 100644 --- a/agents/code-reviewer/AGENT.md +++ b/agents/code-reviewer/AGENT.md @@ -4,7 +4,7 @@ description: Automated code review of pull requests. Reviews PRs for quality, bu # Model: sonnet provides good code understanding for review tasks. # The structured output format doesn't require opus-level reasoning. model: sonnet -skills: forgejo, code-review +skills: gitea, code-review --- You are a code review specialist that provides immediate, structured feedback on pull request changes. @@ -13,8 +13,7 @@ You are a code review specialist that provides immediate, structured feedback on You will receive a PR number to review. Follow this process: -1. Fetch PR diff: `fj pr view <number> diff` (e.g., `fj pr view 42 diff`) - - **Important**: The command is `fj pr view <number> diff`, NOT `fj pr diff <number>` +1. Fetch PR diff using the gitea skill 2. Analyze the diff for issues in these categories: - **Code Quality**: Readability, maintainability, complexity - **Bugs**: Logic errors, edge cases, null checks @@ -22,8 +21,8 @@ You will receive a PR number to review. Follow this process: - **Style**: Naming conventions, formatting, consistency - **Test Coverage**: Missing tests, untested edge cases 3. Generate a structured review comment -4. Post the review via `fj pr comment <number> "<review>"` -5. **If verdict is LGTM**: Auto-merge using `fj pr merge <number> -M rebase -d` (rebase + fast-forward, deletes branch) +4. Post the review as a comment on the PR +5. **If verdict is LGTM**: Auto-merge using rebase style 6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address ## Review Comment Format diff --git a/agents/product-manager/AGENT.md b/agents/product-manager/AGENT.md index 5abf7d2..88d4781 100644 --- a/agents/product-manager/AGENT.md +++ b/agents/product-manager/AGENT.md @@ -4,7 +4,7 @@ description: Backlog management and roadmap planning specialist. Use for batch i # Model: sonnet handles planning and issue-writing well. # Tasks follow structured patterns from skills; opus not required. model: sonnet -skills: forgejo, issue-writing, backlog-grooming, roadmap-planning +skills: gitea, issue-writing, backlog-grooming, roadmap-planning --- You are a product manager specializing in backlog management and roadmap planning. @@ -23,4 +23,4 @@ You can: - Always fetch current issue state before making changes - Ask for approval before creating or modifying issues - Provide clear summaries of actions taken -- Use the `fj` CLI for all Forgejo operations +- Use the gitea skill for all issue/PR operations diff --git a/commands/create-issue.md b/commands/create-issue.md index 0b0dd36..f52a487 100644 --- a/commands/create-issue.md +++ b/commands/create-issue.md @@ -1,17 +1,19 @@ --- -description: Create a new Forgejo issue. Can create single issues or batch create from a plan. +description: Create a new Gitea issue. Can create single issues or batch create from a plan. 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 and ask for description. ## 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 -4. Create each: `fj issue create "<title>" --body "<body>"` +4. Create each issue 5. Display all created issue numbers diff --git a/commands/dashboard.md b/commands/dashboard.md index 0c2e511..3efa708 100644 --- a/commands/dashboard.md +++ b/commands/dashboard.md @@ -4,9 +4,10 @@ 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. +Format as tables showing number, title, and author. diff --git a/commands/groom.md b/commands/groom.md index 0f60955..59eeb04 100644 --- a/commands/groom.md +++ b/commands/groom.md @@ -5,11 +5,11 @@ 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 @@ -17,11 +17,11 @@ Use the backlog-grooming and issue-writing skills. - Acceptance criteria quality - Scope definition 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: Well-defined, can start work diff --git a/commands/plan-issues.md b/commands/plan-issues.md index ea48b18..5a7663f 100644 --- a/commands/plan-issues.md +++ b/commands/plan-issues.md @@ -5,7 +5,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 @@ -29,6 +29,6 @@ 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 after creation 8. **Present summary** with links to created issues diff --git a/commands/review-pr.md b/commands/review-pr.md index e5979b2..7c83361 100644 --- a/commands/review-pr.md +++ b/commands/review-pr.md @@ -1,12 +1,14 @@ --- -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. **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 @@ -15,6 +17,6 @@ Review the changes and provide feedback on: - Documentation Ask the user what action to take: -- **Merge**: Post review summary as comment, then `fj pr merge $1 -M rebase -d` (rebase + fast-forward, deletes branch) -- **Request changes**: `fj pr comment $1 "<feedback>"` - Leave feedback without merging -- **Comment only**: `fj pr comment $1 "<comment>"` - Add a comment for discussion +- **Merge**: Post review summary as comment, then merge with rebase style +- **Request changes**: Leave feedback without merging +- **Comment only**: Add a comment for discussion diff --git a/commands/roadmap.md b/commands/roadmap.md index f1445be..90d6efe 100644 --- a/commands/roadmap.md +++ b/commands/roadmap.md @@ -4,9 +4,9 @@ description: View current issues as a roadmap. Shows open issues organized by st # Roadmap View -Use the forgejo skill. +Use the gitea skill. -1. **Fetch all open issues**: `fj issue search -s open` +1. **Fetch all open issues** 2. **Analyze dependencies** from issue descriptions 3. **Categorize issues**: - Blocked: Waiting on other issues diff --git a/commands/work-issue.md b/commands/work-issue.md index cbee6ad..da4935c 100644 --- a/commands/work-issue.md +++ b/commands/work-issue.md @@ -1,15 +1,17 @@ --- -description: Work on a Forgejo issue. Fetches issue details and sets up branch for implementation. +description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation. 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 based on acceptance criteria 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" 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 diff --git a/docs/writing-agents.md b/docs/writing-agents.md index 065456c..3105e7d 100644 --- a/docs/writing-agents.md +++ b/docs/writing-agents.md @@ -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 diff --git a/docs/writing-commands.md b/docs/writing-commands.md index 66645ab..9a0ebb7 100644 --- a/docs/writing-commands.md +++ b/docs/writing-commands.md @@ -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 ``` diff --git a/docs/writing-skills.md b/docs/writing-skills.md index 8869a30..9e91776 100644 --- a/docs/writing-skills.md +++ b/docs/writing-skills.md @@ -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 ... \``` ``` diff --git a/skills/backlog-grooming/SKILL.md b/skills/backlog-grooming/SKILL.md index afb2a9b..4b1a740 100644 --- a/skills/backlog-grooming/SKILL.md +++ b/skills/backlog-grooming/SKILL.md @@ -60,11 +60,13 @@ If issue covers multiple features, split into separate issues. ## Grooming Workflow -1. **Fetch open issues**: `fj issue search -s open` +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: `fj issue edit <n> --body "..."` -5. **Add labels** as needed: `fj issue label add <n> <label>` +4. **Update issue** with improvements +5. **Add labels** as needed ## Questions to Ask diff --git a/skills/forgejo/SKILL.md b/skills/forgejo/SKILL.md deleted file mode 100644 index 0905010..0000000 --- a/skills/forgejo/SKILL.md +++ /dev/null @@ -1,86 +0,0 @@ -# Forgejo CLI (fj) - -Command-line interface for interacting with Forgejo repositories. - -## Authentication - -The `fj` CLI authenticates via `fj auth login`. Credentials are stored locally by fj. - -## Repository Detection - -`fj` automatically detects the repository from git remotes when run inside a git repository. - -## Common Commands - -### Issues - -```bash -# List issues -fj issue search -s open # Open issues -fj issue search -s closed # Closed issues -fj issue search # All issues - -# View issue details -fj issue view <number> # Full issue details - -# Create issue -fj issue create "<title>" --body "<body>" - -# Edit issue -fj issue edit <number> --title "<new-title>" -fj issue edit <number> --body "<new-body>" - -# Close/reopen -fj issue close <number> -fj issue reopen <number> - -# Labels -fj issue label add <number> <label> -fj issue label remove <number> <label> -``` - -### Pull Requests - -```bash -# List PRs -fj pr search -s open # Open PRs -fj pr search -s closed # Closed/merged PRs - -# View PR -fj pr view <number> # PR details -fj pr view <number> diff # PR diff - -# Create PR -fj pr create "<title>" --body "<body>" -fj pr create "<title>" --body "Closes #<issue>" - -# Comment on PR -fj pr comment <number> "<comment>" - -# Merge -fj pr merge <number> # Default merge -fj pr merge <number> -d # Delete branch after merge -fj pr merge <number> -M squash # Squash commits -fj pr merge <number> -M rebase # Rebase commits -fj pr merge <number> -M rebase-merge # Rebase then merge commit -``` - -### Repository - -```bash -fj repo view # Repository info -fj repo clone <owner>/<repo> # Clone repository -``` - -## Output Formatting - -Most commands support `--output` flag: -- `--output json` - Machine-readable JSON -- `--output table` - Tabular format (default for lists) -- `--output simple` - Plain text - -## Tips - -- Always verify you're in the correct repository before running commands -- Use `fj issue search` to find issue numbers before viewing/editing -- Reference issues in PR bodies with `Closes #N` for auto-linking diff --git a/skills/gitea/SKILL.md b/skills/gitea/SKILL.md new file mode 100644 index 0000000..447ee34 --- /dev/null +++ b/skills/gitea/SKILL.md @@ -0,0 +1,159 @@ +# 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" +``` + +### 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 +tea pulls <number> -f diff # PR diff + +# 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 +``` + +### 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 + +- 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 (API only) + +Note: `tea` CLI does not yet support actions/CI commands. Use the Gitea API directly: + +```bash +# List workflow runs +curl -H "Authorization: token $TOKEN" \ + "https://git.flowmade.one/api/v1/repos/{owner}/{repo}/actions/runs" + +# Get job logs +curl -H "Authorization: token $TOKEN" \ + "https://git.flowmade.one/api/v1/repos/{owner}/{repo}/actions/jobs/{job_id}/logs" +``` diff --git a/skills/roadmap-planning/SKILL.md b/skills/roadmap-planning/SKILL.md index 49e1a08..c3f8a2d 100644 --- a/skills/roadmap-planning/SKILL.md +++ b/skills/roadmap-planning/SKILL.md @@ -75,25 +75,15 @@ In issue descriptions: - Depends on #13 (API setup) ``` -## Creating Issues with fj +## Creating Issues + +Use the gitea skill for issue operations. ### Single Issue -```bash -fj issue create "Add user authentication endpoint" --body "$(cat <<'EOF' -## Summary -Create POST /api/auth/login endpoint for user authentication. - -## Acceptance Criteria -- [ ] Endpoint accepts email and password -- [ ] Returns JWT token on success -- [ ] Returns 401 on invalid credentials -- [ ] Rate limits login attempts - -## Dependencies -- Depends on #5 (user model) -EOF -)" -``` +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: @@ -104,7 +94,7 @@ When creating multiple related issues: ## Roadmap View To see current roadmap: -1. List open issues: `fj issue search -s open` +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