diff --git a/.agents/skills/tangled/README.md b/.agents/skills/tangled/README.md new file mode 100644 index 0000000..6ee3325 --- /dev/null +++ b/.agents/skills/tangled/README.md @@ -0,0 +1,83 @@ +# Tangled Agent Skill + +A platform-neutral Agent Skill for working with [Tangled.org](https://tangled.org/), the decentralized Git code hosting and collaboration platform built on AT Protocol. + +This skill teaches Agent Skills-compatible AI coding agents how to use Tangled for repository hosting, Git operations, issues, pull requests, CI/CD workflows, webhooks, and AT Protocol-related troubleshooting. + +## What this skill covers + +- Tangled Git clone / push / pull / migration / mirroring workflows +- GitHub-to-Tangled concept and command mapping +- Tangled CLI usage patterns (`tang`, `tng`, `tangled`) +- Issue and pull request workflows +- SSH key and authentication troubleshooting +- AT Protocol basics: handles, DIDs, PDS, AppView, knots +- Spindles CI/CD workflows +- Tangled webhooks + +## What this skill does not include + +- No MCP dependency +- No embedded credentials or API keys +- No private SSH keys +- No executable scripts + +It is intentionally written as Markdown-only skill documentation so it can be reused across Agent Skills-compatible and other skill-aware agent environments. + +## Structure + +```text +tangled/ +├── SKILL.md +└── references/ + ├── atproto-troubleshooting.md + ├── cli.md + ├── git-ops.md + ├── github-mapping.md + ├── issues-prs.md + └── knots-spindles-webhooks.md +``` + +## Installation + +Copy the `tangled/` directory into a supported skills directory. + +For global skill-aware agent environments: + +```bash +mkdir -p ~/.agents/skills +cp -R tangled ~/.agents/skills/tangled +``` + +For project-local usage: + +```bash +mkdir -p .agents/skills +cp -R tangled .agents/skills/tangled +``` + +Then start a new agent session so the skill metadata can be discovered. + +## Usage examples + +Ask your agent things like: + +- "Clone this Tangled repo." +- "Push this project to Tangled." +- "Mirror this GitHub repo to Tangled." +- "Create a Tangled issue for this bug." +- "Open a Tangled pull request from this branch." +- "Set up a Spindle workflow." +- "Why is Tangled SSH push failing?" + +## Primary references + +- Tangled: https://tangled.org/ +- Tangled docs: https://docs.tangled.org/ +- Quick start: https://docs.tangled.org/quick-start-guide +- Webhooks: https://docs.tangled.org/webhooks +- `tang` CLI: https://github.com/onevcat/tang + +## License + +MIT, unless a future maintainer chooses a different license file for this repository. diff --git a/.agents/skills/tangled/SKILL.md b/.agents/skills/tangled/SKILL.md new file mode 100644 index 0000000..bc9144d --- /dev/null +++ b/.agents/skills/tangled/SKILL.md @@ -0,0 +1,109 @@ +--- +name: tangled +description: Works with Tangled.org, the decentralized Git code hosting and collaboration platform built on AT Protocol. Use when the user mentions Tangled, tangled.org, knots, spindles, AT Protocol Git hosting, Tangled repositories, Tangled issues, Tangled pull requests, Tangled CI/CD, migrating or mirroring GitHub/GitLab repos to Tangled, or controlling Tangled with git/CLI commands. Does not require MCP. +--- + +# Tangled + +Use this skill for Tangled.org repository work: creating, cloning, pushing, pulling, mirroring, migrating, managing issues/PRs, configuring SSH keys, and setting up Tangled CI/CD/webhooks. + +Tangled is not GitHub with a different domain. It is decentralized Git hosting built around AT Protocol identity, appviews, and repository hosting servers called knots. Prefer standard `git` for code transfer and a Tangled CLI for higher-level objects like issues and pull requests. + +## First decisions + +1. **Need only clone/push/pull/mirror?** Use standard Git commands. Read `references/git-ops.md`. +2. **Need repo creation, SSH keys, issues, or PRs?** Use a Tangled CLI if available. Read `references/cli.md` and `references/issues-prs.md`. +3. **Coming from GitHub/GitLab?** Read `references/github-mapping.md` and `references/git-ops.md`. +4. **Need CI/CD or webhook automation?** Read `references/knots-spindles-webhooks.md`. +5. **Authentication/identity is confusing?** Read `references/atproto-troubleshooting.md`. + +## Safety and verification rules + +- Before running commands that write to a repo or account, inspect the current repository and remotes with `git remote -v`, `git status`, and, if needed, the Tangled CLI status/context command. +- Do not assume a Tangled CLI is installed. Check with `command -v tang`, `command -v tng`, and/or `command -v tangled`. +- Do not install community CLIs globally without the user's approval. If a CLI is missing, explain the options and ask before installing. +- Treat Tangled CLIs as community tools unless the source proves otherwise. Prefer official Tangled docs for Git/SSH/Spindle/Webhook behavior. +- Never expose app passwords, PDS credentials, SSH private keys, tokens, or DID-linked account secrets in chat, logs, commits, or skill files. +- If asked to migrate from GitHub/GitLab, state that Tangled's official docs describe Git history migration via remotes; issues and pull requests are not automatically migrated by the basic Git workflow. +- If the user asks for MCP, say this skill intentionally avoids MCP and can be extended later if needed. + +## Core workflows + +### Clone a Tangled repo + +Use the URL shown by Tangled when possible. Common forms: + +```bash +git clone https://tangled.org/OWNER/REPO +git clone git@tangled.org:OWNER/REPO +``` + +With the `tang` CLI, if installed: + +```bash +tang repo clone OWNER/REPO +``` + +### Push an existing repo to Tangled + +1. Confirm the user already created the Tangled repository or use a CLI to create it. +2. Add or update the remote. +3. Push branches and tags intentionally. + +```bash +git remote add tangled git@tangled.org:OWNER/REPO +git push -u tangled main +git push tangled --tags +``` + +For a full migration: + +```bash +git push -u tangled --all +git push -u tangled --tags +``` + +### Mirror GitHub and Tangled + +For separate control, prefer separate remotes: + +```bash +git remote add github git@github.com:OWNER/REPO.git +git remote add tangled git@tangled.org:OWNER/REPO +git push github main +git push tangled main +``` + +For one remote that pushes to both, see `references/git-ops.md`. + +### Create issues and PRs + +If a Tangled CLI is installed, prefer it over hand-crafting AT Protocol records: + +```bash +tang issue list +tang issue create "Bug: title" --body "Details" +tang pr create --base main --head my-branch --title "Add feature" --body-file ./pr.md +``` + +Command names and flags differ across community CLIs. Verify with `tang --help`, `tng --help`, or `tangled --help` before executing. + +## Reference files + +- `references/github-mapping.md` — GitHub-to-Tangled concept and command mapping. +- `references/git-ops.md` — clone, remote setup, migration, mirroring, SSH remotes. +- `references/cli.md` — known Tangled CLI options and safe CLI selection. +- `references/issues-prs.md` — issue and pull request workflows. +- `references/knots-spindles-webhooks.md` — knots, Spindle CI/CD, webhooks. +- `references/atproto-troubleshooting.md` — DID/PDS/handle basics and common failures. + +## Primary sources + +Use these as the source of truth when current behavior matters: + +- Tangled docs: https://docs.tangled.org/ +- Quick start: https://docs.tangled.org/quick-start-guide +- Single-page docs: https://docs.tangled.org/single-page +- Webhooks: https://docs.tangled.org/webhooks +- Tangled platform: https://tangled.org/ +- `tang` CLI repository: https://github.com/onevcat/tang diff --git a/.agents/skills/tangled/references/atproto-troubleshooting.md b/.agents/skills/tangled/references/atproto-troubleshooting.md new file mode 100644 index 0000000..a2d4f3c --- /dev/null +++ b/.agents/skills/tangled/references/atproto-troubleshooting.md @@ -0,0 +1,88 @@ +# AT Protocol basics and troubleshooting + +Use this when Tangled identity, authentication, SSH, appview visibility, or verification is confusing. + +## Concepts + +- **Handle**: human-readable AT Protocol identifier, often similar to a Bluesky handle. +- **DID**: decentralized identifier, stable identity used internally by AT Protocol records. +- **PDS**: Personal Data Server that stores the user's AT Protocol data. +- **App password**: credential often used by CLIs to authenticate against a PDS. Treat as secret. +- **AppView**: tangled.org's consolidated view into repositories and collaboration records. +- **Knot**: server hosting Git repositories. + +## Auth troubleshooting + +Symptoms: + +- CLI cannot login +- CLI says token expired +- wrong account/handle appears +- issue/PR commands fail despite Git clone working + +Checks: + +```bash +tang auth status +# or equivalent CLI command + +tang status +``` + +Actions: + +- Confirm handle/PDS URL. +- Refresh or re-login with the CLI. +- Use an app password, not the main account password, when the CLI expects app-password auth. +- Do not paste credentials into chat or commit them. + +## SSH troubleshooting + +Symptoms: + +- `Permission denied (publickey)` +- clone/push fails over SSH +- HTTPS clone works but SSH does not + +Checks: + +```bash +git remote -v +ssh -T git@tangled.org +ssh -vT git@tangled.org +``` + +Actions: + +- Ensure the public key is added to Tangled. +- Ensure the private key exists locally and is selected by SSH config. +- If multiple keys exist, add a host block to `~/.ssh/config`. +- After adding a key, allow for indexing/propagation delay if the CLI/docs mention it. + +Example SSH config pattern: + +```sshconfig +Host tangled.org + HostName tangled.org + User git + IdentityFile ~/.ssh/id_ed25519 + IdentitiesOnly yes +``` + +## Repo visibility and empty repo issues + +- A newly created empty repo may not resolve in all views until at least one commit is pushed. +- Some community CLI docs note that records created outside the web UI may lag appview ingestion. If a repo/PR exists but is not visible on tangled.org, verify with CLI/context and check current platform issue status. + +## Commit verification + +If commits are not marked verified: + +- Check whether Tangled supports the signature type being used. +- Confirm the signing key is associated with the correct identity/account. +- Verify local Git signing configuration. +- Refer to the official Tangled troubleshooting docs for current behavior. + +## General rule + +When Tangled behavior differs from GitHub, do not force a GitHub mental model. Identify whether the issue is in Git transport, AT Protocol auth/records, appview indexing, or knot hosting. diff --git a/.agents/skills/tangled/references/cli.md b/.agents/skills/tangled/references/cli.md new file mode 100644 index 0000000..d3eb05e --- /dev/null +++ b/.agents/skills/tangled/references/cli.md @@ -0,0 +1,75 @@ +# Tangled CLI reference + +Tangled has multiple community CLIs. Do not assume one is installed or canonical. Verify before using. + +## Detect available CLIs + +```bash +command -v tang || true +command -v tng || true +command -v tangled || true +``` + +Then inspect help: + +```bash +tang --help +# or +tng --help +# or +tangled --help +``` + +## Known CLIs + +### `tang` by onevcat + +Source: https://github.com/onevcat/tang + +Designed for day-to-day Tangled repository work: + +- `auth`: login, logout, token refresh, token inspection, auth status +- `status`: combined auth, repo, and service status +- `config`: knot, AppView, Constellation, preferred git remote, clone protocol +- `ssh-key`: list/add/delete Tangled SSH public keys +- `repo`: view/list/create/clone repositories +- `issue`: list/create/view/edit/comment/close/reopen issues +- `pr`: list/create/view/diff/comment/checkout/close/reopen/merge pull requests +- `browse`: open Tangled pages from current repo context +- `completion`: shell completions + +Examples: + +```bash +tang auth status +tang status +tang config get clone.protocol +tang config set clone.protocol ssh + +tang ssh-key list +tang repo clone OWNER/REPO +tang repo create my-project --knot KNOT_HOST + +tang issue list +tang issue create "Bug: title" --body "Details" + +git push origin my-branch +tang pr create --base main --head my-branch --title "Add feature" --body-file ./pr.md +``` + +Caveats from the README: + +- `repo create` may require a create-capable knot; pass `--knot` when the default route is insufficient. +- SSH clone may depend on Tangled's SSH key authorization index; after adding a key, retry after key list/index refresh. +- PR merge uses Tangled's merge endpoint and may not support GitHub-style squash/rebase strategies. + +### `tng` and other CLIs + +Other community CLIs exist and may expose similar functions: auth, repo, issue, PR, SSH key, context/config. Their flags and output formats can differ. Use help output as the immediate source of truth. + +## CLI selection policy + +- If `tang` is installed, prefer it because it has broad documented coverage. +- If another CLI is already installed in the user's environment, do not replace it without asking. +- If no CLI is installed and the task can be done with Git, use Git. +- If no CLI is installed and the task requires issues/PRs/repo creation, ask whether to install a CLI or use the Tangled web UI. diff --git a/.agents/skills/tangled/references/git-ops.md b/.agents/skills/tangled/references/git-ops.md new file mode 100644 index 0000000..b0c8ead --- /dev/null +++ b/.agents/skills/tangled/references/git-ops.md @@ -0,0 +1,90 @@ +# Tangled Git operations + +Use standard Git for clone, fetch, pull, push, remote migration, and mirroring. + +## Inspect current repo + +```bash +git status +git remote -v +git branch --show-current +``` + +## Common remote URL forms + +Use the exact URL shown by Tangled when possible. Common examples: + +```bash +https://tangled.org/OWNER/REPO +git@tangled.org:OWNER/REPO +git@tangled.org:user.tngl.sh/my-project +``` + +Older docs/examples may show `user.tngl.sh/my-project`; current repos may also use handle or DID forms. Verify from Tangled UI or CLI before writing remotes. + +## Add Tangled as a separate remote + +This is safest when the user wants explicit control. + +```bash +git remote add tangled git@tangled.org:OWNER/REPO +git push -u tangled main +git push tangled --tags +``` + +## Change origin to Tangled + +Use only when the user wants Tangled as the primary remote. + +```bash +git remote set-url origin git@tangled.org:OWNER/REPO +git push -u origin --all +git push -u origin --tags +``` + +## Mirror while keeping GitHub as primary + +### Separate remotes + +```bash +git remote add github git@github.com:OWNER/REPO.git +git remote add tangled git@tangled.org:OWNER/REPO + +git push github main +git push tangled main +``` + +### One remote with multiple push URLs + +Use when the user wants `git push origin main` to push to both GitHub and Tangled. + +```bash +# Keep fetch URL as the primary remote, then reset push URLs explicitly. +git remote set-url origin git@github.com:OWNER/REPO.git + +git remote set-url --add --push origin git@github.com:OWNER/REPO.git +git remote set-url --add --push origin git@tangled.org:OWNER/REPO + +git remote -v +git push origin main +``` + +After adding multiple push URLs, `git remote -v` should show one fetch URL and multiple push URLs. + +## Full migration + +```bash +git push -u tangled --all +git push -u tangled --tags +``` + +State clearly: this transfers Git refs and history, not GitHub issues, PRs, discussions, releases, or project metadata unless another tool handles them. + +## SSH checks + +```bash +ssh -T git@tangled.org +ssh -vT git@tangled.org +``` + +If SSH fails, check that the public key is uploaded to Tangled, the correct key is selected in `~/.ssh/config`, and the repo URL matches the target owner/repo. diff --git a/.agents/skills/tangled/references/github-mapping.md b/.agents/skills/tangled/references/github-mapping.md new file mode 100644 index 0000000..e0e0425 --- /dev/null +++ b/.agents/skills/tangled/references/github-mapping.md @@ -0,0 +1,25 @@ +# GitHub to Tangled mapping + +Use this when translating familiar GitHub workflows into Tangled workflows. + +| GitHub concept | Tangled equivalent / note | +|---|---| +| `github.com` | `tangled.org` appview plus distributed knots | +| GitHub user/org | AT Protocol handle/DID; repositories are associated with ATProto identity records and hosted on knots | +| GitHub repository hosting | Tangled knot hosting Git data | +| GitHub web UI | Tangled appview at `tangled.org` | +| `gh repo clone` | `git clone ...` or `tang repo clone OWNER/REPO` if CLI installed | +| `gh repo create` | Tangled web UI or `tang repo create`/`tng repo create` if CLI installed and a create-capable knot is available | +| GitHub Issues | Tangled issue records; use Tangled web UI or CLI | +| GitHub Pull Requests | Tangled PR records and patches; use Tangled web UI or CLI | +| GitHub Actions | Spindles workflows under `.tangled/workflows/` | +| GitHub webhooks | Tangled webhooks; currently push events are documented | +| GitHub SSH keys | Tangled SSH public keys, often managed through web UI or `tang ssh-key` | + +## Important differences + +- Tangled is decentralized. A repo may be visible through the appview but hosted by a knot. +- Identity is AT Protocol based: handles, DIDs, and PDS matter for auth and record ownership. +- Basic migration from GitHub/GitLab is Git history only: change/add remotes and push branches/tags. Issues/PRs are not migrated by plain Git. +- PR merge strategies may be narrower than GitHub. The `tang` README notes no GitHub-style squash/rebase strategies for its current merge endpoint. +- Community CLIs may lag platform behavior. Verify with current docs and CLI help. diff --git a/.agents/skills/tangled/references/issues-prs.md b/.agents/skills/tangled/references/issues-prs.md new file mode 100644 index 0000000..5957dee --- /dev/null +++ b/.agents/skills/tangled/references/issues-prs.md @@ -0,0 +1,72 @@ +# Tangled issues and pull requests + +Use this when the user asks to create, view, comment on, close, reopen, review, checkout, or merge Tangled issues/PRs. + +## Before acting + +1. Confirm the current repository context. +2. Check whether a Tangled CLI is installed. +3. Inspect command help because CLI flags differ. +4. For write operations, summarize what will be created/changed before running commands when the action is not obviously requested. + +```bash +git remote -v +command -v tang || command -v tng || command -v tangled || true +``` + +With `tang`: + +```bash +tang status +tang issue list +tang pr list +``` + +## Issues with `tang` + +```bash +tang issue list +tang issue view 5 +tang issue create "Bug: title" --body "Detailed description" +tang issue comment 5 --body "Comment text" +tang issue close 5 +tang issue reopen 5 +``` + +If body content is long, prefer file/stdin patterns if supported: + +```bash +tang issue create "Bug: title" --body-file ./issue.md +``` + +## Pull requests with `tang` + +Typical flow: + +```bash +git checkout -b my-branch +# edit files +git push -u origin my-branch + +tang pr create --base main --head my-branch --title "Add feature" --body-file ./pr.md +``` + +Common operations: + +```bash +tang pr list +tang pr view 3 +tang pr diff 3 +tang pr comment 3 --body "Looks good." +tang pr checkout 3 +tang pr close 3 +tang pr reopen 3 +tang pr merge 3 +``` + +## Caveats + +- Tangled PR identifiers may be numeric in appview contexts or ATProto rkeys in some CLIs. Use the CLI's list/view output to choose the correct identifier. +- PR patches and comments may be stored as ATProto records/blobs depending on CLI implementation. +- Do not assume GitHub semantics like squash merge, rebase merge, required reviews, or branch protection unless the current Tangled docs/CLI confirm them. +- If the user asks to migrate GitHub issues/PRs, do not promise built-in migration. Treat it as a separate import/export project. diff --git a/.agents/skills/tangled/references/knots-spindles-webhooks.md b/.agents/skills/tangled/references/knots-spindles-webhooks.md new file mode 100644 index 0000000..8d7e3fb --- /dev/null +++ b/.agents/skills/tangled/references/knots-spindles-webhooks.md @@ -0,0 +1,71 @@ +# Knots, Spindles, and webhooks + +Use this for Tangled hosting architecture, CI/CD, and automation. + +## Knots + +A knot is a lightweight headless server that hosts Git repositories. Tangled provides managed knots, and users can self-host knots for single-user, home-lab, or community setups. + +Operational implications: + +- Repo creation may require choosing a create-capable knot. +- A repo can be accessible through the tangled.org appview while its Git data lives on a knot. +- When a CLI asks for `--knot`, use the knot host intended to host the repository. +- Self-hosted knot troubleshooting should rely on official docs and service logs. + +## Spindles CI/CD + +Spindles are Tangled's CI/CD workflows. Workflow files live under: + +```text +.tangled/workflows/ +``` + +They are YAML files. Official docs describe triggers such as: + +- `push` — run when a commit is pushed +- `pull_request` — run when a pull request is made or updated +- manual trigger support may exist depending on current docs + +Workflow clone behavior can be customized with a `clone` field. Documented clone options include: + +- `skip`: skip cloning when the workflow does not need repo contents +- `depth`: fetch limited commit history; default examples mention shallow clone behavior +- `submodules`: fetch Git submodules recursively when needed + +When creating or editing workflows: + +1. Check existing `.tangled/workflows/` files first. +2. Keep YAML minimal and explicit. +3. Match trigger names and fields to the current official docs. +4. Do not invent GitHub Actions syntax unless Tangled docs state compatibility. + +## Webhooks + +Official docs: https://docs.tangled.org/webhooks + +Tangled webhooks send HTTP POST notifications to configured URLs. The documented event type is currently `push`. + +Setup fields: + +- Payload URL +- Optional secret for signature verification +- Events, currently push +- Active enabled/disabled state + +Typical headers: + +- `Content-Type: application/json` +- `User-Agent: Tangled-Hook/...` +- `X-Tangled-Event: push` +- `X-Tangled-Hook-ID` +- `X-Tangled-Delivery` +- `X-Tangled-Signature-256: sha256=...` when a secret is configured + +Webhook payload includes before/after SHAs, ref, pusher DID, and repository metadata such as clone URL, HTML URL, SSH URL, name, full name, owner DID, counts, and timestamps. + +When implementing a receiver: + +- Verify HMAC-SHA256 if a secret is configured. +- Respond quickly with 2xx; do longer work asynchronously to avoid retries/timeouts. +- Avoid logging secrets or full payloads if they contain sensitive metadata. diff --git a/skills-lock.json b/skills-lock.json index 07db62a..5957101 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -250,6 +250,12 @@ "skillPath": "skills/writing-plans/SKILL.md", "computedHash": "8990dd5cab321e8128c76684c490eb150f4f5d4b1df14e8f6ee0177b0b92937a" }, + "tangled": { + "source": "git@tangled.org:homebodify.tngl.sh/tangled-skill", + "sourceType": "git", + "skillPath": "SKILL.md", + "computedHash": "9b4c75735748bfd66fd4c05765f02e1d46ccf13a35508f8c44c83a2cafa3d79d" + }, "telemetry-capture": { "source": "dagger/dagger", "ref": "main",