docs

Developer Handbook

This is the project knowledge base. It covers the conventions, workflows, and principles you need to work on gitea-mcp-server. Everything here is available directly — no skill loading required.

Documentation map: See docs/INDEX.md for the full doc set with audience, type, and topic ownership for every document.

---

Documentation philosophy

Code, comments, docstrings, tests, and the docs/ directory together form a single layered knowledge base. Through an index (docs/INDEX.md) this knowledge is navigable, making discovery straightforward.

• Documentation is as much a deliverable as code.
• A doc that says where to look is more valuable than one trying to say everything.
• Always update and improve the documentation. It makes the next job easier.

The structural policies that follow from this philosophy (audience split, de-duplication invariant, pragmatic Diátaxis) live in docs/DOCUMENTATION_STANDARDS.md.

---

RED FLAGS — STOP AND ABORT

• ✗ Starting work without reading the relevant docs/INDEX.md first to navigate the docs
• ✗ Editing files on main branch
• ✗ PR without Fixes #XX reference
• ✗ "Quick fix" that skips issue creation
• ✗ Ignoring test failures
• ✗ Launching a discovery for things already documented
• ✗ Launching a subagent for static code structure discovery (the docs already have module maps, pipeline diagrams, and data flows)

Any of these means: Abort. Create issue, create proper branch, read relevant doc, follow full workflow.

---

Verification Checklist (before PR)

• Branch created from latest main
• Branch name follows type/XX-description format
• All changes on branch, not main
• Documentation, meta docs, docstrings, comments, instructions up to date. This check is NOT optional. Remember: you are intended audience of the documentation.
• No debug/console.log statements
• Tests pass (make test)
• PR body includes Fixes #XX
• Self-review completed