Project Instructions

Problems with a kendex-owned skill go through kendex report; check ownership in the file first.

Project taxonomy

Require one agent and one surface label. Surface means where a person meets the work. Agent names are declared by LINEAR_AGENT_LABELS in kendex.settings.toml. Labels outside these categories are legacy and are not assigned.

Scope: cli, harness and skills belong to team kendex. All other labels in this taxonomy have workspace scope. 1.0 identifies kendex’s release set and requires team scope in a separately approved migration.

Brad Mahaffey owns shared label names and scope. Follow the Linear skill’s Shared label maintenance procedure for definition changes.

{
  "required_categories_for_new_issues": ["agent", "surface"],
  "categories": {
    "agent": {"required": true, "exclusive": true, "match": {"prefix": "agent:"}, "forbid_group_labels": true},
    "surface": {"required": true, "exclusive": true, "labels": ["app", "cli", "skills", "harness", "ci-infra", "docs", "releases"]},
    "stack": {"required": false, "exclusive": false, "labels": ["rust-core", "iced", "test", "security"]},
    "platform": {"required": false, "exclusive": true, "labels": ["macos", "windows", "linux"]},
    "classification": {"required": false, "exclusive": false, "labels": ["bug", "feature", "refactor", "design", "chore", "owner-gated", "1.0"]},
    "workflow": {"required": false, "exclusive": false, "labels": ["research", "needs-research", "baseline", "blocked"]}
  }
}

Project Management

Wrappers run in the primary session: they own the user dialog and every tracker mutation. TPM workflows analyze and return JSON inline; they never mutate the tracker and never write the artifact.

Disposition

• Creation bar. File an issue only when all three hold:

  • it changes what a user or operator experiences, or blocks work that does;
  • no open issue, active branch, or one-line fix already covers it;
  • someone could pick it up and finish it without a new investigation.

  A reproducible anomaly with evidence in hand passes all three as an investigation issue. Everything else is declined with one line in the report: no issue, no placeholder, no tracking artifact. Failing the bar: a severe-sounding edge case no real input reaches, a hypothetical of low severity, a coverage ask for a path that has not regressed, a refactor that neither changes behavior nor unblocks user-visible work, and the classes in ../orch/references/finding-disposition.md § Decision flow Step 0, whatever source the candidate arrived from. Two exceptions file at any likelihood: a security or data-loss defect a shipped path reaches, and an edge case whose failure is critical harm or financial loss.

• Name what reaches it. Every issue carries a Reached by: line giving the user action, run, check, or shipped producer that arrives at the defect; an owner-directed item names the ask.
  • The thread a finding came from, a shape ("a name containing a quote"), or something true in theory is not a reach, and an item with nothing to name is a decline, not an issue. The judgement is the author's: issues create under LINEAR_REQUIRE_REACH refuses only a body with no Reached by: line, an unsubstituted placeholder and a null token (TBD, n/a, none, -) counting as absent.
  • A filing whose source is a review round carries, at priority 2, a Symptom: line naming the run, the user, or the red check that already showed the defect (--review-born). Priority 2 from any other source is structural, reports no symptom, and is not checked for one. Where a review-born finding files at all is ../orch/references/finding-disposition.md § Filing bar.
• Burn down more than you create. Every audit that reads an issue backlog sweeps its comparison set for issues the codebase has already satisfied, duplicated, or superseded, and proposes those for cancellation in the same pass, along with every active issue that fails the creation bar as it stands today. Report created N / closed M. project-order reorders projects, reads no backlog, and does not sweep.
• Ask about work, never about mechanics. Creation and cancellation follow audit-issues § 6; the user decides activation. Labels, priorities, relations, hierarchy, sort order, and project moves are corrections the workflow applies on its own authority.
• Research is part of planning, not a work item. Gather prior art, vendor docs, and approach comparisons inline during planning. Store the artifacts in the tracker under § Planning artifacts. A tracker research issue exists only when the research is delegated as standalone work: run by the researcher agent, or prepared for later pickup (research-spike).
• One approval per decision. Ask the user to approve a body of work once, at the roadmap plan gate. Creation re-asks only what changed after that answer.

Planning artifacts

Planning, research, roadmap, and audit files under docs/ are tracked repository content. Temporary review output belongs under tmp/reviews/. Attach each produced artifact and each cited planning input to the Linear issues the wrapper creates or updates. After the planned mutations for an issue, run issues update [ISSUE_ID] --attach [PATH], repeated per file, as an attach-only call. Include companion files needed to read the artifact, such as roadmap JSON and research metadata. Keep its returned attachments[] entries and add an **Artifacts** list to the issue description: one [repository-relative path](url) link per entry. Replace the prior link for the same path and preserve links to other inputs. Those links identify the published version even when older attachments share the path. Verify every attachment and description write before reporting completion. A run with no issue writes keeps its files locally until creation; it creates no issue only to hold files.

Keep repository-relative references in the brief. Linear attachments are the fallback when a fresh clone lacks a cited file. Resolve it through linear SKILL.md § Resolve a cited artifact.

Carry each planning artifact's repository reference, readable path, and source issue separately. A same-checkout delegation receives the readable path for analysis and the reference for its output. A handoff to another checkout carries the reference and the issue that holds the attachment; the receiver resolves its own readable path through the Linear rule above. Saved plans and tracker text contain references and source issues, never cache paths. A source issue identifies storage, not the roadmap's hierarchy origin. With no published source issue, keep the existing local-until-creation flow.

For a GitHub audit, put the produced text artifact in the created or updated issue body, and include the text of any cited planning input needed for pickup. Report binary inputs that have no tracker upload route as incomplete; never claim a local-only file is available to another lane. A run without artifacts retains its existing tracker behavior.

Commands

audit-issues is primary-session only (audit-issues preamble): the roadmap-plan § 5 answer that roadmap-create carries in is validated and admitted at § 6, never around it.

The @[path] given to roadmap plan may be research findings or a finished plan (a design the user has reviewed). A finished plan is the spec: derive issues from it instead of re-planning, and every issue cites it.

TPM analysis workflows, each returning JSON per its schema: tpm-cycle-plan, tpm-audit (project / team / issue / project-order modes), tpm-roadmap-plan.

Execution Rules

• Run workflow sections in order. Skip only on an explicit Skip if condition, never on your own scope assessment.
• <delegation_format> and <output_format> are literal templates: fill [PLACEHOLDERS], drop lines whose placeholders are empty, add nothing.
• Send a user-visible <output_format> report as a normal assistant message first, then invoke the question tool separately with only the question and short option labels. Never paste the report into question text or options.
• The Linear cache holds the whole workspace: sync sends no team filter, and cache issues list returns no team through its safe, compact, ids or table formatter, so a row read through those cannot be checked against --team X (only --format=raw carries .team.name). Team scope per path: § Scope by Path.
• Sync the Linear cache before a workflow's first cache read: sync --reconcile in a run that mutates the tracker, sync --if-stale 15 in a read-only lookup. That sync is the freshness mechanism; a cached read itself enforces presence, so a read that comes back missing halts the workflow and reports the sync failure, never a partial result, a live-only substitute, or a retry against the unsynced cache.
• Resolve tracker context once per run (audit-issues § 1.2) and route every preflight, fetch, and mutation through it. A GitHub-tracked run must not require Linear installation, sync, or authentication; where GitHub lacks a Linear concept, degrade in a documented note, never silently.
• Before any issue create or label update, run the label preflight in references/labels.md against the live inventory and project taxonomy; any § Validation failure there halts before mutation.
• A project declares its taxonomy in one of the sources references/labels.md names: inline in its kendex manifest under [skill-instructions] for this skill (kendex.toml, or kendex-local.toml in a source-catalog checkout), which renders it into § Project Instructions above, or in a project document or reference file those instructions link to. A project that declares none in any of them has no required categories to enforce.
• In multi-issue analysis, keep verification context per issue. One issue's PR, branch, or resolved path set never scopes another's checks.

Scope by Path

The Linear cache is workspace-wide, so each path states whether it resolves the team scope (tpm-audit § 1.1.1) and what it filters. Silence is not inheritance: a new mode adds its row.

Hierarchy

Initiative → Project → Milestone → Issue → Sub-Issue. Parent and child must share a project; blocking relations may cross projects freely. See references/dependencies.md.

Contracts