11f86f5d99
Closes #27. PROJECT.md - Git section: TBD as the convention. Commit to main, one logical change per commit, `task check` locally before push, CI is the quality gate. PRs only for the parallel-agent exception. - Agent rule 6: rewritten to match. .gitea/workflows/cd.yml - Drop the pull_request trigger — vestigial under TBD. - Drop the `if: github.event_name != 'pull_request'` guard on the build job (now always true since pull_request no longer fires). Tag pushes still build (no version gating regression). - Deploy `if` left alone — already correctly limits deploy to main pushes, skipping tag-push builds. .githooks/pre-push (new) - Runs `task check` before every push. Set up via `task setup:hooks`, which sets core.hooksPath to the in-repo .githooks dir. Taskfile.yml - New `setup:hooks` task to install the pre-push hook on a fresh clone. README.md - Quickstart section showing `task setup:hooks` + the TBD policy. Derived adapters regenerated via `task context:sync` and committed in the same commit (single-commit invariant). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
108 lines
4.6 KiB
Markdown
108 lines
4.6 KiB
Markdown
# Project context
|
|
|
|
<!-- Canonical project context. Edit this, run `task context:sync`.
|
|
Root agent context from ~/dev/.context/AGENT.md is automatically
|
|
prepended for harnesses that don't walk the directory tree. -->
|
|
|
|
## Identity
|
|
|
|
- **Name**: gitea-mcp
|
|
- **Owner**: Mathias
|
|
- **Client**: personal
|
|
- **Repo**: https://gitea.d-ma.be/mathias/gitea-mcp
|
|
- **Status**: active
|
|
|
|
## Stack
|
|
|
|
- **Primary language**: Go
|
|
- **UI layer**: HTMX + Templ (when applicable)
|
|
- **Fallback languages**: Python, TypeScript (justify in PR if used)
|
|
- **Build**: Task (taskfile.dev), not Make
|
|
- **Containers**: Docker (compose for dev, k3s for deploy)
|
|
- **Target infra**: koala (GPU workloads), iguana (services), flamingo (edge)
|
|
|
|
## Conventions
|
|
|
|
### Code style
|
|
- Go: follow `golines`, `gofumpt`, `golangci-lint` with project config
|
|
- Tests: table-driven, in `_test.go` next to source, `testify` for assertions
|
|
- Errors: wrap with `fmt.Errorf("operation: %w", err)`, no naked returns
|
|
- Naming: stdlib conventions, no stuttering (`http.Client` not `http.HTTPClient`)
|
|
|
|
### Architecture preferences
|
|
- Prefer standard library over frameworks (net/http over gin/echo)
|
|
- Dependency injection via constructor functions, not containers
|
|
- Configuration via environment variables, parsed at startup into a typed struct
|
|
- Structured logging via `slog`
|
|
|
|
### Git
|
|
- Conventional commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
|
|
- **Trunk-Based Development:** commit directly to main. One logical change per commit.
|
|
- Run `task check` locally before every push. CI is the quality gate, not branch protection.
|
|
- No feature branches, no PRs for solo/agent work.
|
|
- Exception: if a parallel agent session is active on this repo, use a short-lived
|
|
`agent/<description>` branch and merge within the same session.
|
|
|
|
### Security
|
|
- No secrets in code, ever — use env vars or SOPS-encrypted files
|
|
- Client data never leaves local network unless explicitly cleared
|
|
- Dependencies: audit with `govulncheck` before adding
|
|
|
|
## Knowledge base access
|
|
|
|
This project can query the shared knowledge base via MCP or HTTP:
|
|
|
|
- **MCP endpoint**: `mcp://localhost:3100/knowledge`
|
|
- **HTTP fallback**: `http://localhost:3100/api/v1/search`
|
|
- **Scoping**: queries are filtered to collection `personal` + `public`
|
|
|
|
## Behavior rules
|
|
|
|
These rules apply to every task in this project, regardless of harness.
|
|
|
|
1. **No assumptions.** Don't hide confusion — surface it. Surface tradeoffs explicitly.
|
|
Think before coding; if the problem is unclear, ask or state assumptions before acting.
|
|
2. **Minimum viable code.** Solve with the smallest change that works. Nothing
|
|
speculative, no "while we're here" cleanups, no premature abstractions. Simplicity first.
|
|
3. **Surgical changes.** Touch only what the task requires. Leave unrelated code,
|
|
files, and formatting alone. Diffs should be small and reviewable.
|
|
4. **Goal-driven execution.** Define clear success criteria up front for every task.
|
|
Loop — implement, verify, refine — until those criteria are met. Don't claim
|
|
completion without evidence (tests pass, command output, observed behavior).
|
|
|
|
## Agent instructions
|
|
|
|
When acting as a coding agent on this project:
|
|
|
|
1. Read this file and all `SKILL.md` files in `.skills/` before starting work
|
|
2. Run `task check` before committing (lint + test + vet)
|
|
3. If unsure about a convention, check `DECISIONS.md` or ask
|
|
4. Never modify files outside the project root without explicit permission
|
|
5. When adding a dependency, explain why in the commit message
|
|
6. Commit directly to main. Run `task check` before every push. Never create
|
|
feature branches unless a parallel agent is simultaneously active on this repo.
|
|
7. For client projects: never send code or context to cloud APIs — use local models via LiteLLM
|
|
|
|
## Current state — v0.2.5 (2026-05-17)
|
|
|
|
All v0.2 work is complete and deployed. No active sprint.
|
|
|
|
### What shipped
|
|
|
|
| Tag | PR | Tools / fixes |
|
|
|-----|----|---------------|
|
|
| v0.2.2 | #21 | repo_create, repo_update, repo_mirror_push |
|
|
| v0.2.3 | #22 | repo_tree, repo_topics_update, file_read dir fix |
|
|
| v0.2.4 | #23 | issue_get, release_create, repo_delete |
|
|
| v0.2.5 | #26 | repo_update archived+template, create_project_from_template template_name, pr_files_diff loop fix |
|
|
|
|
Current main: `e31fd3f`. CI green. Deployed via Flux.
|
|
|
|
### Next up
|
|
|
|
1. **`hyperguild new-project` v1** — primary next target.
|
|
See brain node `adr-new-project-gitea-first-github-mirror` for full flow spec.
|
|
|
|
2. **Issue #19** — end-to-end mirror flow verification.
|
|
`repo_mirror_push` is implemented but the full flow (create repo → add push mirror → verify sync to GitHub) has not been tested manually. Do this before relying on it in production.
|