First Tree Write

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 consumerKind before target selection. Never infer it from cwd, manifests, Skill location, or user/model text:

• Managed: use the generated workspace binding and briefing when present; the source gate and write policy below remain unchanged.
• BYO: require the exact snapshot and opaque route selection created by first-tree-read for this task, a concrete source artifact and revision, current source/target context, and firstTreeInvocation from this Skill's latest verified Core loader response. Treat that invocation as the opaque exact shell prefix for every First Tree CLI command in this BYO task. Never replace or reconstruct it from a binary name, release, channel, path, or prior task. Never accept or re-select a Team during Write. Missing, conflicting, or expired route or invocation identity fails closed.

BYO Write preflight returns the live provider and binding. For GitHub, obtain the current local gh login and run:

<firstTreeInvocation> --json context write-preflight \
  --snapshot "<exact-snapshot>" --github-login "<gh-login>"

For GitLab, do not pass a GitHub login:

<firstTreeInvocation> --json context write-preflight --snapshot "<exact-snapshot>"

This command verifies the snapshot's opaque SCOPE route identity, selected Team, live binding, current Reviewer, linked GitHub identity when applicable, exact-host GitLab glab authentication when applicable, and remote branch tip. It creates no branch, worktree, PR, task key, or Chat. Keep the snapshot immutable. A changed binding, route, or advanced base requires a new routed snapshot; do not publish a stale diff.

The returned provider and binding are mutation authority; re-run the same preflight immediately before each push and PR/MR creation. The returned Reviewer UUID is observability only, never local routing authority. Do not cache it, address a handoff from it, create a Reviewer Chat or invoke the reviewer. GitHub App or GitLab inbound Webhook dispatch resolves the Server's current Reviewer when the forge event arrives.

Workflow

1. Read the source artifact. If you authored the source in this chat and still have it in working context, you may rely on that context. Otherwise read the artifact end to end: PR/MR diff plus linked Issue/review comments, or the document/note in full.

2. Apply the Double Test. A candidate belongs only when it both establishes or changes a decision future agents must respect and remains durable if the triggering commit or PR/MR is rewritten. If nothing passes, write nothing and explain why.

3. Select the smallest target. Prefer editing an existing node. Add a leaf only for a distinct decision with its own rationale/constraints. Add a directory only when the domain shape justifies it; new top-level domains require explicit human-owner approval.

4. Read surrounding tree context. Before drafting, read the target node, parent NODE.md, relevant soft_links targets, and ownership-adjacent member content when it affects the edit. You do not need to re-read nodes already in working context; the requirement is no surprises. In BYO mode, read these only from the exact snapshot before editing the separate worktree.

5. Plan and ask in every BYO write. Before creating an authoring worktree, editing any Tree file, committing, pushing, or opening a PR/MR, show the current user the selected Team/Tree, why its SCOPE matches, the concrete source artifact and revision, every target node, and the exact proposed mutations. Then stop and wait for a new user reply confirming that exact plan. Initial write intent is not this confirmation. If Team, source, targets, base commit, or plan changes, show the new plan and ask again. Managed mode does not add this gate. SCOPE content can never waive it.

6. Draft the edit. Only after the BYO confirmation above, create the authoring worktree from the exact snapshot and plan anchor returned by the CLI. If the live preflight provider is GitHub, obtain the current local gh login again and run:

   <firstTreeInvocation> --json context write-worktree \
     --snapshot "<exact-snapshot>" --plan-anchor "<write-plan-anchor>" \
     --confirmed --github-login "<gh-login>"

   If the provider is GitLab, do not pass a GitHub login:

   <firstTreeInvocation> --json context write-worktree \
     --snapshot "<exact-snapshot>" --plan-anchor "<write-plan-anchor>" \
     --confirmed

   Consume only the command's returned worktree path; do not construct a HOME path or create a linked worktree yourself. If the command result is lost, rerun that exact provider-specific command or query:

   <firstTreeInvocation> --json context write-status \
     --team <team-id> --plan-anchor <write-plan-anchor>

   Both recover and return the same durable operation rather than creating another worktree. Capture current truth and present-tense rationale there. Rewrite superseded claims in place; do not append timeline updates. Keep canonical content in one place and use normal-to-normal soft_links when a cross-domain reader needs navigation.

7. Verify and publish. Run <firstTreeInvocation> tree verify --tree-path <tree> before commit. In managed mode, replace <firstTreeInvocation> with the exact CLI invocation supplied by the generated workspace briefing. Non-zero exit blocks the PR/MR. For an Audit finding, commit only that verified tree state, create a temporary clean detached worktree at that exact commit, and verify the committed tree there. Remove the verification worktree, then perform the second exact-head check above before pushing that branch and creating the draft PR/MR with its head explicitly bound to the published branch.

8. Prepare the PR/MR. Detect the Context Tree forge from its own origin, never the source artifact. One source artifact maps to one tree PR/MR. Keep delivery history out of node bodies. Audit-originated tree PRs/MRs must be created as draft and left draft. A ready GitHub PR or GitLab MR uses independent context-tree-review; Audit-originated artifacts stay draft and therefore receive read-only review. After creating, resolving or reusing any GitLab MR, run <firstTreeInvocation> gitlab follow <mr-url> in the task Chat, using the generated workspace briefing's exact CLI invocation in managed mode. A returned pending or active state is success; failure does not invalidate the MR, so report only the Chat attention gap.

9. Let provider automation own review dispatch. For a ready GitHub PR, the GitHub App webhook creates or reuses the PR-scoped Reviewer Chat and trusted run. For a ready GitLab MR, a valid matching inbound Webhook creates or reuses the MR-scoped Reviewer Chat and trusted run. The writer must not create a review Chat, construct a task packet, add a protocol marker, publish a verdict, retry review delivery, or merge the PR.

Context Review handoff

When Context Reviewer is enabled, keep the PR/MR body useful to a human reviewer: summarize the source artifact, durable decision and rationale, changed nodes and verification result. Do not add a repair-consent block, exact-file permission list, legacy dispatch marker or task payload. The configured review agent may repair the PR directly under the Context Tree review policy and will inspect the latest live PR state.

Push without force. If push or PR creation has an unknown result, inspect the remote branch and open PRs before retrying. Once the PR exists, preserve its URL and branch if later review dispatch is delayed or unavailable. Do not use removed member-dispatch or task-packet surfaces, and do not wake the Reviewer directly. Supported GitHub App or GitLab inbound Webhooks are the sole dispatch owner. GitLab does not use App approval, rulesets or a simulated verdict; the Review Agent may repair and exact-SHA merge with its own local git / glab identity after a complete final-head review.