RSS Reader using AT Protocol
rssbase.io
feed
atom
rss
reader
atproto
social
improve agent docs for tangled issues
Romain Gautier
(Jul 7, 2026, 8:55 PM +0200)
5078c2ff
7c998234
+106
-27
+2
-2
.agents/skills/code-review/SKILL.md
+2
-2
.agents/skills/code-review/SKILL.md
···
26
26
27
27
Look for the originating spec, in this order:
28
28
29
-
1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, etc.) — fetch via the workflow in `docs/agents/issue-tracker.md`.
29
+
1. Issue references in the commit messages (`#123`, `Closes #45`, GitLab `!67`, Tangled rkeys/AT URIs, etc.) — resolve them with `docs/agents/issue-tracker.md`.
30
30
2. A path the user passed as an argument.
31
-
3. A PRD/spec file under `docs/`, `specs/`, or `.scratch/` matching the branch name or feature.
31
+
3. A PRD/spec/design file matching the branch name or feature. First read `docs/README.md` to understand this repo's documentation map, then search only the locations that map identifies as relevant to product intent, architecture decisions, or design/spec material. Do **not** scan the whole `docs/` tree as if every doc were a spec.
32
32
4. If nothing is found, ask the user where the spec is. If they say there isn't one, the **Spec** sub-agent will skip and report "no spec available".
33
33
34
34
### 3. Identify the standards sources
+10
-7
docs/README.md
+10
-7
docs/README.md
···
2
2
3
3
This repo uses a Diátaxis-inspired documentation structure.
4
4
5
-
- **Tutorials** teach by walking through a learning path.
6
-
- **How-to guides** solve a specific practical problem.
7
-
- **Reference** records facts, options, APIs, commands, and configuration.
8
-
- **Explanation** gives background, reasoning, architecture, and trade-offs.
5
+
Also read root `CONTEXT.md` for the RSSBase glossary and ubiquitous language.
9
6
10
-
## Structure
7
+
## Where things go
11
8
12
-
- `docs/agents/` — configuration consumed by agent skills.
9
+
- `docs/product/explanation/` — product and domain background.
13
10
- `docs/architecture/explanation/` — architectural background and system explanations.
14
11
- `docs/architecture/decisions/` — architectural decision records, named like `0001-use-atproto-for-user-data.md`.
15
12
- `docs/development/how-to/` — developer task recipes.
16
13
- `docs/development/reference/` — developer reference material.
17
-
- `docs/product/explanation/` — product and domain explanations.
14
+
- `docs/agents/` — agent operating instructions and tracker setup.
15
+
16
+
## Agent setup
17
+
18
+
- Issue tracker: `docs/agents/issue-tracker.md`
19
+
- Triage labels: `docs/agents/triage-labels.md`
20
+
- Domain docs: `docs/agents/domain.md`
+94
-18
docs/agents/issue-tracker.md
+94
-18
docs/agents/issue-tracker.md
···
1
1
# Issue tracker: Tangled
2
2
3
-
Issues and PRDs for this repo live as Tangled issues. Use the `tang` CLI for issue operations.
3
+
Issues and PRDs live as Tangled issues for `mykiwi.dev/rssbase.io`. Pull requests are also on Tangled: <https://tangled.org/mykiwi.dev/rssbase.io/pulls>.
4
4
5
-
Pull requests are also managed through Tangled. Use the `tang` CLI when possible, and the web UI at <https://tangled.org/mykiwi.dev/rssbase.io/pulls> when needed.
5
+
Use `tang` for supported workflows. If `DEVENV_ROOT` is not set, wrap project tools with `devenv shell ...`.
6
6
7
-
## Conventions
7
+
## Before using `tang`
8
8
9
-
- Inspect available commands with `tang --help`, `tang issue --help`, and `tang pr --help` before using a workflow for the first time.
10
-
- Use `tang issue list` to list issues.
11
-
- Use `tang issue create` to create issues.
12
-
- Use `tang issue view` or the closest available command to read an issue and comments.
13
-
- Use `tang issue comment`, `tang issue edit`, or the closest available command to update issues, labels, and comments.
14
-
- Use `tang pr list`, `tang pr view`, `tang pr create`, or the closest available commands for pull request workflows.
15
-
- Prefer the repository inferred from the current git remote: `git@tangled.org:mykiwi.dev/rssbase.io`.
9
+
```bash
10
+
git remote -v
11
+
tang status
12
+
tang --help
13
+
tang issue --help
14
+
tang pr --help
15
+
```
16
16
17
-
Command names and flags may vary with the installed `tang` version. Verify with help output before writing.
17
+
If a command needs an explicit repository, use `-R mykiwi.dev/rssbase.io`.
18
18
19
-
## When a skill says "publish to the issue tracker"
19
+
## Issues
20
20
21
-
Create a Tangled issue using `tang issue create`.
21
+
```bash
22
+
tang issue list -R mykiwi.dev/rssbase.io
23
+
tang issue create "short imperative title" -R mykiwi.dev/rssbase.io --body-file issue-body.md
24
+
tang issue view 1 -R mykiwi.dev/rssbase.io
25
+
tang issue edit 1 -R mykiwi.dev/rssbase.io --title "new title"
26
+
tang issue comment 1 -R mykiwi.dev/rssbase.io --body "comment text"
27
+
tang issue close 1 -R mykiwi.dev/rssbase.io
28
+
tang issue reopen 1 -R mykiwi.dev/rssbase.io
29
+
```
22
30
23
-
## When a skill says "fetch the relevant ticket"
31
+
Numeric issue arguments are Tangled AppView issue numbers. For AT URIs or rkeys, inspect `tang issue view --help`; use `--atproto` when required.
24
32
25
-
Read the Tangled issue using `tang issue view` or the current equivalent from `tang issue --help`.
33
+
## Pull requests
26
34
27
-
## Pull requests as a triage surface
35
+
```bash
36
+
tang pr list -R mykiwi.dev/rssbase.io
37
+
tang pr view 1 -R mykiwi.dev/rssbase.io
38
+
tang pr create -R mykiwi.dev/rssbase.io --base main --head feature/branch --title "short title" --body-file pr-body.md
39
+
tang pr diff 1 -R mykiwi.dev/rssbase.io
40
+
tang pr comment 1 -R mykiwi.dev/rssbase.io --body "comment text"
41
+
tang pr checkout 1 -R mykiwi.dev/rssbase.io
42
+
tang pr close 1 -R mykiwi.dev/rssbase.io
43
+
```
28
44
29
-
Pull requests are available through Tangled using the `tang` CLI or the web UI at <https://tangled.org/mykiwi.dev/rssbase.io/pulls>.
45
+
Treat PRs as related repo work, but prefer Tangled issues as the main request surface unless a maintainer or skill asks otherwise.
30
46
31
-
Treat pull requests as related repo work, but prefer Tangled issues as the main request surface unless a skill or maintainer explicitly asks to triage PRs.
47
+
## Issue bodies
48
+
49
+
Prefer concise, agent-friendly issue bodies:
50
+
51
+
```md
52
+
## Goal
53
+
One or two sentences describing the outcome.
54
+
55
+
## Scope
56
+
- [ ] concrete task or behavior
57
+
58
+
## Acceptance criteria
59
+
- [ ] observable result or verification command
60
+
```
61
+
62
+
## Triage labels
63
+
64
+
Use the labels from `docs/agents/triage-labels.md`:
65
+
66
+
- `needs-triage` — default for new unsorted tickets.
67
+
- `needs-info` — missing requirements or reproduction details.
68
+
- `ready-for-agent` — clear scope and acceptance criteria.
69
+
- `ready-for-human` — needs human judgement or maintainer-only access.
70
+
- `wontfix` — rejected or obsolete.
71
+
72
+
Tangled labels are repo subscriptions. The current `tang` CLI may not expose label commands; if `tang issue edit --help` has no label flags, apply labels in the Tangled web UI. Do not invent unsupported `tang label` commands.
73
+
74
+
## Commit-message and PR references
75
+
76
+
Resolve references manually:
77
+
78
+
- `#123`, `issue #123`, `closes #123`, `fixes #123` → `tang issue view 123 -R mykiwi.dev/rssbase.io`.
79
+
- `PR #123`, `pull #123`, `!123`, `/pulls/123` → `tang pr view 123 -R mykiwi.dev/rssbase.io`.
80
+
- AT URIs or rkeys → inspect the relevant `view --help`; use `--atproto` when required.
81
+
82
+
Tangled may not auto-link every GitHub/GitLab-style commit reference.
83
+
84
+
## Skill workflows
85
+
86
+
When a skill says **publish to the issue tracker**, create a Tangled issue and verify it with `tang issue view`.
87
+
88
+
When a skill says **fetch the relevant ticket**, read it with `tang issue view` or `tang pr view`.
89
+
90
+
## Wayfinding operations
91
+
92
+
`tang` does not currently expose native sub-issue or blocking-edge commands. For wayfinder maps, encode relationships in issue bodies:
93
+
94
+
```md
95
+
## Parent
96
+
- #<parent>
97
+
98
+
## Blocked by
99
+
- #<blocking-issue>: reason
100
+
101
+
## Children
102
+
- #<child>: short title
103
+
```
104
+
105
+
## Safety
106
+
107
+
Do not expose app passwords, PDS credentials, access tokens, SSH private keys, or DID-linked account secrets. Do not assume GitHub semantics unless Tangled docs or CLI output confirm them.