Fonti delle attività

Technical reference synchronized with Yard’s source. File names and development commands refer to the native app repository.

New project connections use Yard's integrated board. GitHub Projects remains available in the connection sheet. Existing configurations without tracking retain their GitHub behavior. The task source is independent of the GitHub repository used to create, review and merge pull requests.

The native client creates tasks through the existing draft editor, opens their descriptions and activity in the inspector, and edits titles, labels, descriptions and status. Tasks start in Backlog. Verification commands and a working code-host connection are needed for agent delivery, not for using the local board.

Configuration and persistence

{
  "tracking": { "driver": "yard" },
  "repo": { "path": "/path/to/project", "remote": "owner/repository" }
}

tracking.driver selects yard, github or an installed plugin identifier. GitHub also uses the existing project.owner and project.number settings. Unknown configuration keys remain intact.

Yard stores local tasks in .yard/tasks/<configuration-slug>/board.json. It stores opaque IDs, stable numeric handles, revisions, comments, status, labels, assignments and explicit PR links. Creates carry a publication identifier: repeating a confirmed create returns the same task, while changing its original content is rejected. Writes and exclusive claims use a process lock and atomic replacement. Unrecognized or corrupt board versions fail without overwriting the file. Private .yard/ data is excluded through Git's local exclude file.

The first task read or write records the source identity in .yard/task-connections/<slug>.json; browsing an empty board leaves the source editable. A used configuration cannot be silently repointed at another source: use another configuration for a different connection. Handoffs, branches, worktrees and preview names for non-GitHub tasks include the source and configuration namespace, preventing task #1 in Yard from sharing the workspace of GitHub issue #1.

Task source changes do not migrate tasks or historic evidence. Yard keeps the existing GitHub configuration and receipts compatible. The local board does not require a server, GitHub Projects permissions or a public webhook.

Delivery and approvals

The engine retains Build → QA → Review → Done. qa tasks can skip Build. Labels, blockers, claims, continuation, Studio handoffs and collection operate on the selected driver. New local configurations collect architecture/code signals by default; external signal sources can be enabled separately.

A project with a non-GitHub task source and no GitHub repository uses local delivery: no remote, gh or PR is needed. yard-board-merge-gate --task <n> --branch <branch> --expect-head <sha> applies the same policy and verification, then squash-merges into the local base branch. Gate records live in .yard/delivery/. Human approvals are written by Yard under agents/approvals/ in Application Support, outside the project, and pin the exact commit and policy scope.

With a GitHub repository, GitHub remains responsible for code, PRs, collaborators, diffs, checks and merging. A local task links to an actual PR explicitly, storing both its repository and number. Local task numbers are never interpreted as GitHub issue numbers, and PR bodies must not use Closes #<local-number>.

Approval requests and confirmations for local tasks live on the linked PR. The merge gate still checks the human identity, repository permissions, exact reviewed head and policy scope. An edited head invalidates the approval. Local comments and task status never authorize a merge. A successful Review requires GitHub to confirm the merge and the engine to prove ancestry on the fetched remote base.

CLI

The app and both agents executables use the same engine. Run from the repository, or supply --root with a separate path argument. Paths and body files may contain spaces.

yard-agents onboard demo --tracker yard
yard-agents card create --title "Export data" --body-file "/tmp/task body.md" --label feature --request-id export-v1
yard-agents card items
yard-agents card get 1
yard-agents card edit 1 --title "Export table data" --body-file "/tmp/task body.md"
yard-agents card comments 1
yard-agents card comment 1 --body-file "/tmp/task evidence.md"
yard-agents card move 1 Ready
yard-agents card link-pr 1 --pr 113
yard-agents card close 1

To create a GitHub connection, use onboard <slug> --tracker github --owner <owner> --number <board> --repo <repo> --verify <command>. The existing --number option also selects GitHub for compatibility. Configure real verification commands before running agents. Closing a task manually does not merge its code.

Installed worker helpers expose the same card subcommands as .claude/bin/yard-board-card. Agent prompts select the correct task transport while retaining GitHub's guarded PR helpers. Imported upstream skills are unchanged.

Executable plugins: driver API version 1

Install a prepared plugin package under $YARD_HOME/plugins/task-tracking/<id>/ (normally ~/Library/Application Support/Yard/plugins/task-tracking/<id>/). It appears in the task-source picker the next time the connection sheet is opened. Yard never discovers executable plugins from repository content.

The package contains manifest.json, its executable and any bundled runtime, plus its licenses. Users should not need to compile it or install Homebrew, Node or Python. A manifest looks like:

{
  "id": "example",
  "version": "1.0.0",
  "api_version": 1,
  "executable": "bin/example-driver",
  "capabilities": ["list", "get", "create", "update", "move", "comments", "comment", "claim", "close"]
}

The executable must stay within the package. At least list and get are required. Other capabilities are optional; unsupported operations fail before execution. Agent delivery additionally requires update, move, comments, comment and exclusive claim support. The app uses capabilities to disable unsupported editing and publication actions.

The host launches one process per request, writes one JSON-RPC 2.0 request to stdin and expects one JSON object on stdout. Diagnostics belong on stderr. The process has a 30-second deadline. Plugins run with the user's ordinary process privileges; a separate process is crash isolation, not an operating-system permission boundary.

{
  "jsonrpc": "2.0",
  "id": "request-uuid",
  "method": "tasks.get",
  "params": {
    "connection": "demo",
    "settings": { "team": "example-team" },
    "arguments": { "number": 7 }
  }
}

The response echoes id and jsonrpc, with either result or a JSON-RPC error containing a message. Only tracking.settings is passed to the plugin, not the project's AI or unrelated integration configuration. Settings must contain non-secret identifiers or credential references; plugins own service authentication and should use the macOS Keychain for credentials. The protocol does not currently provide a general OAuth setup UI.

A full record has opaque string id, positive integer number, string title, body, state (OPEN or CLOSED), labels and assignees. Preserve the service's opaque ID separately as external_id. Handles must be stable across restarts and must not be reused for different remote tasks. Normalize this worker's claim identity to yard-agent, retaining other assignees. A plugin can persist its own handle mapping rather than converting a service ID to an integer.

List items use { "id": "card-id", "status": "Ready", "content": <full-record> }; content can include type: "Task" and comments. Canonical statuses are Backlog, Ready, Building, QA, Review, Blocked and Done. A plugin maps its external workflow to these statuses. Include pull_requests and pull_request_repository in the task record when the engine links a GitHub PR through tasks.update. That link belongs to the configured code repository.

Incomplete lists, duplicate handles and mismatched task responses are rejected. Mutations are journaled under .yard/runtime/<slug>/task-plugin-mutations/ before execution. An interrupted or malformed response leaves an uncertain receipt; the host never repeats that write automatically. Reconcile it with the provider before clearing the pending receipt. Explicit JSON-RPC errors are recorded as rejected operations.

The executable test fixture in PluginTaskDriverTests.swift demonstrates the protocol. No Linear plugin is bundled yet; adding one uses this contract without changing the board or the engine's delivery policy.