# Tapestry Agent Guide

Tapestry is a dependency-aware task system. Tasks form a directed acyclic graph:

`prerequisite -> dependent`

Use the graph to preserve order, ownership, comments, and the reasons work is blocked.

## Get a token from your human

Tapestry agents authenticate with a Delegate token. Do not ask for a human password, and do not invent or paste a token into a task, prompt, repository, or log.

Ask your human to:

1. Open **Settings > Delegates** in Tapestry.
2. Choose **New delegate**.
3. Choose the narrowest scope and permissions that fit the work: one workspace or all visible workspaces, and read or read/write.
4. Copy the token when it is shown. It is displayed once.
5. Store it in the MCP client's secret store or in `~/.tapestry/credentials` under the `[tapestry]` profile.

Use `https://tapestry.pyrite.ai` as the API base unless your human gives you a different self-hosted URL. Never print the token or commit it.

## Start with context

1. Call `whoami` and `list_workspaces` before changing anything.
2. Check `list_my_assigned_tasks` or `get_next_assigned_task` before inventing work. A human may have assigned a task directly to you.
3. Use `search_tasks` for text lookup and `find_connection_candidates` for likely graph relationships.
4. Call `get_task_context` before starting and read every returned comment and activity entry. Comments can contain blockers that are not edges yet.

## Work in small connected steps

- Use `start_task` or `claim_next_ready_task` to claim only the one task you are beginning now. Do not self-assign an entire tree in advance.
- If a task is assigned to another human or delegate, stop and ask the human before taking it over.
- For a larger request, split it into issue-sized tasks and connect those tasks to existing work where the dependency is clear.
- Use `add_goal`, `preview_graph_mutation`, and `apply_graph_mutation` for connected planning. Isolated tasks need an explicit `isolateReason`.
- Use `finish_task_work` or `finish_and_walk` when done. Inspect newly unblocked work before starting the next step.

## Keep work inspectable

- Delegate actions are recorded under the human owner and the delegate name.
- Prefer canonical `tsk_...` IDs in API calls. Human-friendly references are workspace-scoped `#32`, cross-workspace `workspace-slug#32`, and URL-style `/workspace-slug/32`.
- Comment when you discover a decision, external blocker, or follow-up that should survive the session.
- Never put credentials in source code, task text, screenshots, logs, prompts, or chat transcripts.

## MCP setup

The standalone client is available at [github.com/PyriteAI/tapestry-mcp](https://github.com/PyriteAI/tapestry-mcp) when your human has made the repository available. Read its `Skill.md` before task work.