From 5078c2ffb55762fcd7d82f9cd207c39a9137852d Mon Sep 17 00:00:00 2001 From: Romain Gautier Date: Tue, 7 Jul 2026 20:55:50 +0200 Subject: [PATCH] improve agent docs for tangled issues --- .agents/skills/code-review/SKILL.md | 4 +- docs/README.md | 17 +++-- docs/agents/issue-tracker.md | 112 +++++++++++++++++++++++----- 3 files changed, 106 insertions(+), 27 deletions(-) diff --git a/.agents/skills/code-review/SKILL.md b/.agents/skills/code-review/SKILL.md index 2a0b524..07b9092 100644 --- a/.agents/skills/code-review/SKILL.md +++ b/.agents/skills/code-review/SKILL.md @@ -26,9 +26,9 @@ Before going further, confirm the fixed point resolves (`git rev-parse . -Pull requests are also managed through Tangled. Use the `tang` CLI when possible, and the web UI at when needed. +Use `tang` for supported workflows. If `DEVENV_ROOT` is not set, wrap project tools with `devenv shell ...`. -## Conventions +## Before using `tang` -- Inspect available commands with `tang --help`, `tang issue --help`, and `tang pr --help` before using a workflow for the first time. -- Use `tang issue list` to list issues. -- Use `tang issue create` to create issues. -- Use `tang issue view` or the closest available command to read an issue and comments. -- Use `tang issue comment`, `tang issue edit`, or the closest available command to update issues, labels, and comments. -- Use `tang pr list`, `tang pr view`, `tang pr create`, or the closest available commands for pull request workflows. -- Prefer the repository inferred from the current git remote: `git@tangled.org:mykiwi.dev/rssbase.io`. +```bash +git remote -v +tang status +tang --help +tang issue --help +tang pr --help +``` -Command names and flags may vary with the installed `tang` version. Verify with help output before writing. +If a command needs an explicit repository, use `-R mykiwi.dev/rssbase.io`. -## When a skill says "publish to the issue tracker" +## Issues -Create a Tangled issue using `tang issue create`. +```bash +tang issue list -R mykiwi.dev/rssbase.io +tang issue create "short imperative title" -R mykiwi.dev/rssbase.io --body-file issue-body.md +tang issue view 1 -R mykiwi.dev/rssbase.io +tang issue edit 1 -R mykiwi.dev/rssbase.io --title "new title" +tang issue comment 1 -R mykiwi.dev/rssbase.io --body "comment text" +tang issue close 1 -R mykiwi.dev/rssbase.io +tang issue reopen 1 -R mykiwi.dev/rssbase.io +``` -## When a skill says "fetch the relevant ticket" +Numeric issue arguments are Tangled AppView issue numbers. For AT URIs or rkeys, inspect `tang issue view --help`; use `--atproto` when required. -Read the Tangled issue using `tang issue view` or the current equivalent from `tang issue --help`. +## Pull requests -## Pull requests as a triage surface +```bash +tang pr list -R mykiwi.dev/rssbase.io +tang pr view 1 -R mykiwi.dev/rssbase.io +tang pr create -R mykiwi.dev/rssbase.io --base main --head feature/branch --title "short title" --body-file pr-body.md +tang pr diff 1 -R mykiwi.dev/rssbase.io +tang pr comment 1 -R mykiwi.dev/rssbase.io --body "comment text" +tang pr checkout 1 -R mykiwi.dev/rssbase.io +tang pr close 1 -R mykiwi.dev/rssbase.io +``` -Pull requests are available through Tangled using the `tang` CLI or the web UI at . +Treat PRs as related repo work, but prefer Tangled issues as the main request surface unless a maintainer or skill asks otherwise. -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. +## Issue bodies + +Prefer concise, agent-friendly issue bodies: + +```md +## Goal +One or two sentences describing the outcome. + +## Scope +- [ ] concrete task or behavior + +## Acceptance criteria +- [ ] observable result or verification command +``` + +## Triage labels + +Use the labels from `docs/agents/triage-labels.md`: + +- `needs-triage` — default for new unsorted tickets. +- `needs-info` — missing requirements or reproduction details. +- `ready-for-agent` — clear scope and acceptance criteria. +- `ready-for-human` — needs human judgement or maintainer-only access. +- `wontfix` — rejected or obsolete. + +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. + +## Commit-message and PR references + +Resolve references manually: + +- `#123`, `issue #123`, `closes #123`, `fixes #123` → `tang issue view 123 -R mykiwi.dev/rssbase.io`. +- `PR #123`, `pull #123`, `!123`, `/pulls/123` → `tang pr view 123 -R mykiwi.dev/rssbase.io`. +- AT URIs or rkeys → inspect the relevant `view --help`; use `--atproto` when required. + +Tangled may not auto-link every GitHub/GitLab-style commit reference. + +## Skill workflows + +When a skill says **publish to the issue tracker**, create a Tangled issue and verify it with `tang issue view`. + +When a skill says **fetch the relevant ticket**, read it with `tang issue view` or `tang pr view`. + +## Wayfinding operations + +`tang` does not currently expose native sub-issue or blocking-edge commands. For wayfinder maps, encode relationships in issue bodies: + +```md +## Parent +- # + +## Blocked by +- #: reason + +## Children +- #: short title +``` + +## Safety + +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. -- 2.51.2