🔧 update docs
This commit is contained in:
@@ -0,0 +1,33 @@
|
||||
# Domain Docs
|
||||
|
||||
How the engineering skills should consume this repo's domain documentation when exploring the codebase.
|
||||
|
||||
## Before exploring, read these
|
||||
|
||||
- **`CONTEXT.md`** at the repo root, or
|
||||
- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
|
||||
- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
|
||||
|
||||
If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
|
||||
|
||||
## File structure
|
||||
|
||||
This repo is single-context:
|
||||
|
||||
```
|
||||
/
|
||||
├── CONTEXT.md
|
||||
└── docs/adr/
|
||||
```
|
||||
|
||||
## Use the glossary's vocabulary
|
||||
|
||||
When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
|
||||
|
||||
If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
|
||||
|
||||
## Flag ADR conflicts
|
||||
|
||||
If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
|
||||
|
||||
> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_
|
||||
@@ -0,0 +1,44 @@
|
||||
# Issue tracker: Gitea (self-hosted)
|
||||
|
||||
Issues and specs for this repo live as issues on the self-hosted Gitea instance at `https://git.lukas-harat.com`, repo `lukas/Ghost_Kitchen`. There's no CLI (`tea` isn't installed here), so all operations go through Gitea's REST API (`/api/v1`) via `curl`, authenticated with a personal access token read from the `GITEA_TOKEN` environment variable.
|
||||
|
||||
## Conventions
|
||||
|
||||
Base URL: `https://git.lukas-harat.com/api/v1/repos/lukas/Ghost_Kitchen`
|
||||
Auth header on every request: `-H "Authorization: token $GITEA_TOKEN"`
|
||||
|
||||
- **Create an issue**: `POST /issues` with JSON body `{"title": "...", "body": "..."}`. Note: Gitea's create-issue endpoint only accepts label **IDs** (not names) in its `labels` field — create the issue first, then add labels by name (below).
|
||||
- **Read an issue**: `GET /issues/{index}`. Comments separately via `GET /issues/{index}/comments`.
|
||||
- **List issues**: `GET /issues?state=open&type=issues`. Filter by label client-side (via `jq`) since query-string label filtering wants label IDs, not names.
|
||||
- **Comment on an issue**: `POST /issues/{index}/comments` with `{"body": "..."}`.
|
||||
- **Apply labels**: `POST /issues/{index}/labels` with `{"labels": ["needs-triage"]}` — this endpoint accepts label **names** directly, unlike issue creation.
|
||||
- **Remove a label**: `DELETE /issues/{index}/labels/{id}` — this one needs the numeric label ID; look it up via `GET /labels` and `jq` on `name`.
|
||||
- **Close**: `PATCH /issues/{index}` with `{"state": "closed"}`. Post the closing comment first (`POST .../comments`), then close — this call has no comment field.
|
||||
- **Ensure labels exist**: `GET /labels` to check; `POST /labels` with `{"name": "...", "color": "#hex"}` to create any of the five canonical labels that are missing before first use.
|
||||
|
||||
## Pull requests as a triage surface
|
||||
|
||||
**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/triage` reads this flag.)_
|
||||
|
||||
When set to `yes`, use the `/pulls` endpoints in place of `/issues` (`GET /pulls`, `GET /pulls/{index}`; the comment/label/close calls above are shared between issues and PRs in Gitea's API). Determine "external" by comparing the PR author against `GET /repos/lukas/Ghost_Kitchen/collaborators` — an author who isn't a collaborator or the repo owner is external.
|
||||
|
||||
Gitea numbers issues and PRs from one shared counter per repo (like GitHub), so a bare `#42` may be either; resolve with `GET /issues/42` and fall back to `GET /pulls/42` (or vice versa).
|
||||
|
||||
## When a skill says "publish to the issue tracker"
|
||||
|
||||
Create a Gitea issue via `POST /issues`.
|
||||
|
||||
## When a skill says "fetch the relevant ticket"
|
||||
|
||||
`GET /issues/{index}` plus `GET /issues/{index}/comments`.
|
||||
|
||||
## Wayfinding operations
|
||||
|
||||
Used by `/wayfinder`. The **map** is a single issue with **child** issues as tickets.
|
||||
|
||||
- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body.
|
||||
- **Child ticket**: an issue carrying `Part of #<map>` at the top of its body and label `wayfinder:<type>` (`research`/`prototype`/`grilling`/`task`) — this Gitea version (1.27.2) has no native sub-issue link, so the task-list/text-reference fallback is the only option here. Once claimed, assign the driving dev (`PATCH /issues/{index}` with `{"assignees": ["<username>"]}`).
|
||||
- **Blocking**: Gitea's **native issue dependencies** — the canonical representation (confirmed available on this instance via its swagger spec). Add one with `POST /issues/{child}/dependencies` body `{"index": <blocker-index>, "owner": "lukas", "repo": "Ghost_Kitchen"}` — this makes the child depend on (i.e. be blocked by) the blocker. List with `GET /issues/{index}/dependencies`. A ticket is unblocked when every listed dependency is closed.
|
||||
- **Frontier query**: list the map's open children, drop any with an open (not-closed) entry in `GET /issues/{index}/dependencies` or an assignee; first in map order wins.
|
||||
- **Claim**: `PATCH /issues/{index}` with `{"assignees": ["<username>"]}`, the session's first write.
|
||||
- **Resolve**: `POST /issues/{index}/comments` with the answer, then `PATCH /issues/{index}` with `{"state": "closed"}`, then append a context pointer (gist + link) to the map's Decisions-so-far.
|
||||
@@ -0,0 +1,15 @@
|
||||
# Triage Labels
|
||||
|
||||
The skills speak in terms of five canonical triage roles. This file maps those roles to the actual label strings used in this repo's issue tracker.
|
||||
|
||||
| Label in mattpocock/skills | Label in our tracker | Meaning |
|
||||
| --------------------------- | --------------------- | ----------------------------------------- |
|
||||
| `needs-triage` | `needs-triage` | Maintainer needs to evaluate this issue |
|
||||
| `needs-info` | `needs-info` | Waiting on reporter for more information |
|
||||
| `ready-for-agent` | `ready-for-agent` | Fully specified, ready for an AFK agent |
|
||||
| `ready-for-human` | `ready-for-human` | Requires human implementation |
|
||||
| `wontfix` | `wontfix` | Will not be actioned |
|
||||
|
||||
When a skill mentions a role (e.g. "apply the AFK-ready triage label"), use the corresponding label string from this table.
|
||||
|
||||
These labels may not exist yet in the Gitea repo — see the "Ensure labels exist" step in `issue-tracker.md` to create any that are missing before first use.
|
||||
Reference in New Issue
Block a user