Project Instructions

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

VGS delivery policy overrides the shared workflow's mandatory review, CI-wait, branch-size and commit-hook gates. Work targets main. Reviews and PRs are optional; push directly or merge a PR immediately with gh, without a review loop, queue or CI wait. Do not arm git guards. Run scripts/validate once on the final relevant diff; use --changed for a fix round, and reuse passing results while those inputs are unchanged. Do not rerun a full battery at commit, push or submission. Use --full only for an explicit full sweep or an unmapped dependency. Keep the live-session safety rules.

Linear projects

Every new issue, including manually mirrored GitHub intake, belongs to team vgs and the V2 Shell project.

Project	Scope
V2 Shell	The plugin-first Hyprland shell on Quickshell: core, plugins, surfaces, configuration, themes, validation and repository tooling.

V1 and its legacy projects are reference-only; do not route new work there. Creating a new project is an owner decision: propose it, do not create it unprompted.

Project issue label taxonomy

Use this taxonomy with the linear skill's label-inventory preflight for roadmap creation, audit-created issues, research issues, and any other issue create/update path.

Required for new non-historical issues:

• Exactly one Agent label.
• Classification and Workflow labels are optional and additive.
• Domain labels apply when the work clearly sits in that domain.

Label creation rule: if a label listed here is missing from live Linear inventory, stop and ask for explicit user authorization to create it. Do not create labels automatically and do not silently omit or substitute labels.

Agent labels (exclusive; choose exactly one)

Label	Use when
agent:generalist	Maintenance, docs cleanup, tooling/workflow tasks, repository organization, or mixed low-risk work — including QML/Go/helper implementation until dedicated domain agents exist.
agent:multi	Bundle parent or coordination issue whose children span 2+ domains. Avoid on leaf implementation issues unless the issue is truly orchestration-only.
agent:human	Manual/user-owned work, external dependency/vendor action, or work intentionally not delegated to an AI agent.
agent:researcher	Research issue owned by the researcher workflow/agent. Must be paired with research.

agent:iced and agent:rust are workspace-level labels inherited by every team; they serve other projects (hyprtrade), so never assign them in VGS.

Domain labels (non-exclusive; choose all that apply)

Label	Use when
ci-infra	CI, review gates, runners, and repo tooling — the validation suite, .github/workflows/, packaging automation.
test	Testing itself: coverage, harnesses, fixtures, flakes. Pairs with ci-infra when the harness is CI-owned.
app	UI-surface work: shell surfaces under shell/Hosts/ and plugin interfaces under shell/plugins/.
design	Visual design, tokens, typography and surface layout; theme rules are in docs/architecture/configuration.md.
component	Reusable widget/control work, especially primitives in shell/Ui/.
releases	Cutting a release, versioning, and publishing to the distribution channels.

Priority rule: ci-infra implies Urgent unless the issue deliberately records why it is lower. Everything VGS uses to decide whether a change is safe to merge lives in that category, so a defect there invalidates the evidence behind every other issue's "verified" claim.

Classification labels (non-exclusive; additive)

Label	Use when
bug	Defect in shipped behavior.
enhancement	New feature or request.
chore	Mechanical/maintenance work, no behavior change.
docs	Documentation work.
security	Security-relevant surface or hardening work.
refactor	Restructure/migration/cleanup where behavior should mostly remain unchanged.
research	Research spike/issue whose primary output is findings/decision support. Pair with agent:researcher.
baseline	Establishes a measurement baseline, benchmark fixture, golden data, or pre-optimization reference.

Workflow labels (non-exclusive; additive)

Label	Use when
needs-research	Blocked on unresolved research. Prefer a blocking relation to a research issue when one exists.
needs-review	Requires an explicit review gate before execution/merge/close.
needs-safety-audit	Concurrency, lock-free, memory/thread safety, or safety-critical validation required.
needs-perf-test	Benchmark/profiling/performance validation required before acceptance.
critical-path	Blocks or enables major project progress; align priority accordingly.
blocked	External blocker only (vendor/license/access/manual dependency). For issue dependencies, use blocking relations instead.
owner-gated	Needs an owner decision or owner-only action to proceed.
hardware-blocked	Blocked on physical hardware or device/OS access — a second monitor, a fingerprint reader, an Apple display — rather than on a decision or another issue.
re-triage	Request one triage-janitor pass (Linear Loop 2) over an issue whose labels, project, or priority look wrong. The automation REMOVES it when the pass completes, so it is a trigger, not a state — an issue carrying it long-term means the loop did not run. Expect zero issues to carry it at rest.

ci-nightly marks CI-failure mirrors; the taxonomy above does not apply to mirrored issues — do not retitle or relabel them to satisfy it. Note there is no automated ingest: mirroring GitHub intake into Linear is manual, per the tracker policy in the linear skill instructions.

Never-use labels

These are live in the workspace and must never be assigned in VGS. The reason matters as much as the verdict: a label omitted with no explanation reads as an oversight, and gets "fixed" by someone assigning it.

Label	Why never
Agent	Group/parent label. Assign one of its children, never the group itself.
Platform	Group/parent label, same rule.
ios	VGS is a Linux Wayland shell for Hyprland. Can never apply.
macos	Same.
windows	Same.
cross-platform	Same — VGS targets exactly one platform, so nothing here is cross-platform.
linux	Vacuously true for every VGS issue, so it carries no information.
agent:iced	Workspace-level label inherited by every team; serves hyprtrade.
agent:rust	Same.
iced	Same.
rust-core	Same.
1.0	Kendex's release label. It does not classify VGS work.
feature	VGS uses enhancement for new functionality. The workspace-level feature label may serve another team; do not delete it or assign it here.

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. The fleet proposal sweep runs in a subagent the overseer launches and returns its analyzed JSON to the overseer.

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; single files one item against the open titles and does not sweep either.

• 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. A plan or report with no caller-supplied path lives at docs/plans/<slug>.md (a research report at docs/plans/<slug>-research.md), tracked, never under tmp/; the full rule, with its roadmap exception, is agents/planner.md § Plan Artifacts. 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

Command	Arguments	Workflow
cycle-plan	none	cycle-plan
audit-issues	project | project "Name" | team | issue [IDs] | --issues [file] | --single [file] | --analyzed [file] | project-order	audit-issues
roadmap plan	[feature] | [feature] @[research-or-plan-path]	roadmap-plan
roadmap create	@[plan-file]	roadmap-create
research-spike	none	research-spike
research-complete	[ISSUE_ID]	research-complete
research-issue	none	research-issue, internal, invoked by research-spike
proposal-sweep	fleet brief	proposal-sweep, internal, invoked by oversee

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 / single / 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.

Path	Resolves	Filters
tpm-audit project, team	yes	§ 1.3 projects, § 1.4 input set, § 1.5 comparison set
tpm-audit issues, Linear	yes	§ 1.5 comparison set; a § 1.4 input issue outside scope halts
tpm-audit issues, GitHub	n/a, reads no Linear cache	n/a
tpm-audit single, Linear	yes	§ 1.3 projects, § 14 title list
tpm-audit single, GitHub	n/a, reads no Linear cache	n/a
tpm-audit project-order	yes	§ 11 initiatives, projects, and per-project issues
tpm-roadmap-plan	yes, § 1.1	§ 1.4 projects, § 1.5 comparison set
tpm-cycle-plan	no	no. session-status picks the active project workspace-wide, and every later read is scoped to that pick
audit-issues §§ 7.2-7.5	n/a, executes an artifact tpm-audit produced under its scope	reads rooted at an in-scope project or an issue this run mutated
audit-issues § 1.2.1, § 3	no	no. session-status selects projects workspace-wide
cycle-plan, roadmap-plan, roadmap-create, research-spike	no	no. Project, initiative, and label reads span the workspace
research-complete	n/a	reads are rooted at the caller's issue identifier
research-issue	n/a	reads rooted at the caller's identifiers; the project it creates into is the caller's pick

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

Kind	Files
Schemas	audit-issues-input, audit-output, roadmap-plan-input, roadmap-plan-output, cycle-plan-output
Templates	issue-description-template, parent-issue-template
References	labels, dependencies
Tracker CLI	Linear: .agents/skills/linear/scripts/linear.sh; GitHub: gh + .agents/skills/github/scripts/github.sh