Christoph Görn b469158944

chore: 🚀 add OpenSpec workflow, beads issue tracker, and merge PR proposal

- Add OpenSpec artifact-driven workflow (.claude/commands/opsx/, .claude/skills/openspec-*)
- Add beads git-backed issue tracker (.beads/)
- Add git hooks for workflow automation (.husky/)
- Add "Landing the Plane" session completion workflow to AGENTS.md
- Create merge-pull-request proposal (openspec/changes/merge-pull-request/)

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

2026-01-30 08:25:11 +01:00

2.9 KiB

Raw Permalink Blame History

AGENTS.md

This file provides guidance to AI coding assistants (Claude Code, Cursor, etc.) when working with this repository.

For detailed developer documentation, see DEVELOPER.md.

Quick Reference

make build          # Build the binary (outputs ./forgejo-mcp)
make vendor         # Tidy and verify Go module dependencies

Architecture Summary

main.go → cmd/cmd.go (CLI parsing) → operation/operation.go (tool registration) → operation/{domain}/*.go (tool handlers)

Key directories:

operation/ - MCP tool definitions and handlers by domain
pkg/forgejo/ - Singleton Forgejo SDK client wrapper
pkg/to/ - Response formatting helpers
pkg/params/ - Shared parameter descriptions

Adding a New Tool

Create or modify a file in operation/{domain}/
Define tool with mcp.NewTool() and implement handler function
Register in the domain's RegisterTool(s *server.MCPServer) function
If new domain, import and call in operation/operation.go

See DEVELOPER.md for complete code examples and patterns.

Blocked Features

Some features are blocked on upstream API/SDK support. See docs/plans/ for:

wiki-support.md - Wiki API (blocked on forgejo-sdk)
projects-support.md - Projects/Kanban API (blocked on Gitea 1.26.0)

Repository Labels

Labels for goern/forgejo-mcp on Codeberg:

ID	Name	Color	Description
335058	Kind/Feature	0288d1	New functionality
335061	Kind/Enhancement	84b6eb	Improve existing functionality
335091	Status/Blocked	880e4f	Something is blocking this issue or pull request
335103	Priority/Medium	e64a19	The priority is medium

Usage with Codeberg MCP

When adding labels via the mcp__codeberg__add_issue_labels tool, use the numeric ID:

mcp__codeberg__add_issue_labels(
  owner: "goern",
  repo: "forgejo-mcp",
  index: <issue_number>,
  labels: "<label_id>"  # e.g., "335091" for Status/Blocked
)

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

git pull --rebase
bd sync
git push
git status  # MUST show "up to date with origin"

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
Hand off - Provide context for next session

CRITICAL RULES:

Work is NOT complete until git push succeeds
NEVER stop before pushing - that leaves work stranded locally
NEVER say "ready to push when you are" - YOU must push
If push fails, resolve and retry until it succeeds

2.9 KiB Raw Permalink Blame History