/first-tree-write

name: first-tree-write
version: 0.16.7
cliCompat:
  first-tree: ">=0.5.16 <0.6.0"
description: Source-driven Context Tree write workflow for managed and BYO consumers. BYO always requires the exact SCOPE-routed read snapshot and a new user confirmation of the precise Team/source/targets/mutation plan before any Tree mutation. If no source artifact is available, there is no write task.

First Tree Write

Use this skill when a specific source artifact should be reflected into the Context Tree. The generated `AGENTS.md` / `CLAUDE.md` Context Tree Policy is the baseline for what belongs in the tree; this skill applies that policy to a source-backed write.

Use `first-tree-read` for task-scoped tree reads before acting, except when the source is a current-session Audit finding whose exact snapshot context is already loaded. Use this skill only for source artifact -> tree edit work.

Unbound or broken Tree binding

Evaluate this gate before the Source Gate below. When the trusted briefing reports no usable binding, the response is only the binding gap this section defines — the Source Gate's stop-and-ask for a source artifact never applies, because there is no write task to source.

A missing Context Tree removes only the operations that depend on it. Nothing in this skill may prompt the user to bind, create, or connect a Tree merely because one is absent.

• **Explicitly unbound:** when the trusted managed briefing explicitly states

there is no bound Tree, no Tree write is possible and there is no write task. Continue the underlying work from the source artifact and locally available inputs without Tree operations. A leftover `.first-tree/workspace.json` manifest or `context-tree/` checkout from a previously bound session may still be on disk — it is inert residue, and this gate precedes any disk discovery: never read, trust, or recover from it. If the user explicitly asked for a Tree write, state only that this Tree write cannot be completed because no Tree is bound; do not expand the absence into bind/create guidance. An explicit first-time Tree creation request routes to `first-tree-seed`, not this skill.

• **Declared but broken:** "broken" means the binding metadata, resolved

path, or upstream identity is malformed or inconsistent — in that case keep failing closed for Tree operations — never guess a Tree. Report the binding gap; the broken binding blocks only the Tree write, never unrelated work. A fully declared binding whose local checkout simply does not exist yet is not broken: materialize it per Tree Location before drafting and continue.

Source Gate

Writing is source-driven. Acceptable sources include:

• a PR/MR, forge Issue, commit discussion, or review thread;
• a design doc, meeting note, decision note, or pasted source material;
• a source repo change you just completed, when its design decision now needs

durable tree context;

• an evidence-backed `context-tree-audit` finding from the current session that

records the exact audited tree HEAD and scope, path, generated-policy rule, current source evidence, confidence, intended replacement or canonical placement, and risk, and comes from an Audit request that explicitly granted Maintenance mutation authority.

The always-visible generic route uses non-exhaustive examples from the Skill's discovery surface. It does not promote a source repo change you just completed or an Audit finding to generic routing: the former still requires an explicit Tree-write request or a later concrete routed artifact, and the latter enters only through the `context-tree-audit` Maintenance handoff. This Source Gate remains intentionally broader than the generic automatic route.

If no concrete source artifact exists, stop and ask for one. Do not invent ad-hoc tree edits from memory or from a broad request like "update the tree". When the source repo or issue lives on GitHub or GitLab, read local code, history, and existing files from the filesystem and plain `git` first; use its matching CLI (`gh` or `glab`) only for forge reads the filesystem cannot answer — PR/MRs, issues, review comments, provider metadata — and for publish actions. A missing or unauthenticated CLI blocks only that forge step; source reading and local drafting continue without it. Before any tree push or review request, detect the Context Tree forge from its own `origin`; never infer it from the source.

An Audit finding is valid only for its recorded tree HEAD. Before any target selection, worktree creation, or mutation, fetch the bound upstream default branch and require its exact remote HEAD to equal the finding's audited HEAD. If it advanced, do not apply the old finding. Re-run Audit validation, target and source-evidence reads on a new exact snapshot, or fail closed without a tree diff or PR/MR.

For an Audit finding, repeat that fetch and exact remote-HEAD comparison after drafting and verification, immediately before any push or PR/MR creation. If the default branch advanced during authoring, do not publish. Safely remove the unpublished Audit-origin worktree and local branch, then re-run Audit on a new exact snapshot or stop with no remote branch and no PR/MR.

Implementation-only material usually produces no tree write. Refactors, function signatures, API shapes, request/response examples, build config, fixtures, and one-off bug fixes stay in source repos unless the source also establishes a durable decision, constraint, ownership change, or cross-domain relationship.

Routing classification and mutation authority are separate. An always-visible runtime contract may classify a concrete artifact as a Tree-write task before this Skill loads; that standing classification selects this workflow but never bypasses its live write preflight. Authorization to publish a source PR/MR is not, by itself, a separate or transitive Tree write-intent rule.

Invocation Modes

Choose one mode from the trusted standing `consumer