vanillagreencom/kendex/project-management

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

• Judge the approach. At every filing and launch read, judge the approach against the item's own outcome sentence:

1. Why does this approach produce the stated outcome, and what source evidence will show it? An outcome sentence plus a measurement does not show the work helps.
2. Can we remove or simplify something instead of adding this? Name the existing owner or the simpler alternative and why it meets or fails the same need. Naming an owner alone is no answer. A new requirement is not forced into a removal.
3. Is this a workaround of a limit, a rule or a tool? If yes, does the limit or rule still have a reason? Correct or remove a stale rule in its owning place. Fix the cause. Escalate only a boundary the owner reserves. Apply orch SKILL.md § Skill Rules and code-quality SKILL.md § Correctness and § Over-Engineering.

• Decide go, change or drop. Put the short cause-and-effect answer in the item's existing outcome, evidence or ruling text.
• Repair an item with a valid need and weak text on the same item from its source request. Keep its date. Drop it only when the need is absent, duplicated, satisfied or superseded.

• 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. A container, a parent with children in the tracker or named by identifier in its body, has no work of its own, so the three tests do not apply to it; the rework-parent rule below files and keeps it. Children sharing its subject are no duplicate; each child faces the bar itself. A parent with no child and none named is a work item. 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 `../reviewer/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.

• One rework parent per pass. Every end-to-end audit, holistic pass, redesign or grouping pass files one rework parent for its subject first; every item it produces is its sub-issue. Items form a parent when 3 or more share one outcome or mechanism, an audit or redesign produces more than one child, or the owner asks to read a subject in one place; otherwise they stay single. A parent carries no requirements, no pull request and one Done-when box, "Every child Done or cancelled"; an outcome to read is its own child (parent-issue-template). Audits file it per tpm-audit § 7.1.
• 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 `../reviewer/references/finding-disposition.md` § Filing bar.
• A requirement asks for what code-quality admits. A requirement, Done-when or test plan is written against the code-quality skill's SKILL.md § Tests, § Over-Engineering and the repository's compatibility policy under § Cleanup. A wording test, a fixed count of growing data, a compatibility or migration clause the policy does not require, or a gate with no named failure is cut from the item before filing; the cited section states each rule.
• An estimate is a relative size. The numeric estimate is a size class within the team, 1 for its smallest work through 5 for its largest, never a unit of time. An estimate already set stays valid. State time beside the item, not in the field: one approximate number of nonstop hours from a lane starting the work through merge, review rounds included. The communication skill's references/messages.md § Evidence and costs says how to derive and label it.
• Done-when separates branch proof from live proof. Prove every box the branch can prove before merge. Admit a post-merge box on the same item only when all three conditions hold. It needs something the branch cannot give: a deployment or installation (a release, consumer refresh or host), live use over time, or a person's screen or hands. Name that class in Why after merge:. Its Where: names the evidence location and its reader under orch communication-modes.md § Owner-only verification. For owner-side account, browser and home steps, write "Jarvis, the owner's delegate" in Where:. The repository's normal traffic produces its sample inside the window. A release trigger names a release the repository publishes within 72 hours of merge. A count names its sample size. Otherwise make it a pre-merge test or drop it. Write each such box on one line as - [ ] Post-merge: <check>; Where: <location or command>; Why after merge: <why the branch cannot prove it>; Trigger: <trigger>; Deadline: <deadline>. The Post-merge: check states its pass condition. Trigger is merge, a UTC time at or after merge, or release OWNER/REPO TAG-GLOB, the first matching GitHub release published after merge. When OWNER/REPO is a repository where the item merged, the release must contain the item's latest merge commit in that repository. A missing Trigger means merge. Deadline is +Nh, with N from 1 through 72, counted from the trigger: the merge, the stated time, or the release publication. Write a merge trigger's deadline as +Nh, because the merge time is unknown when the box is written. A merge or time trigger also takes a real UTC deadline after its trigger and at most 72 hours later; a release trigger takes only +Nh. The Linear completion command validates this form. Admit a count or rare-event check only when an existing query or counter answers it inside this window. Otherwise make it a pre-merge test or drop it. Absence of an event passes only when the check states absence as its pass condition. An open post-merge box keeps the merged item in Verifying. The verification pass records evidence and ticks a passing box, then completes the same item after its last box. A failed check follows orch § The Cycle. Unreadable evidence and deadline moves follow orch verify. A merged item never returns to In Progress. Do not create a separate item to carry the verification check.
• One item per batch. A body that lists batches each able to land alone is filed as one item per batch, with a blocking relation only where a batch needs another's change.
• One landing per subsystem. An item whose work changes more than one subsystem, as the orch skill's small.md opening defines one, is filed as one item per subsystem, each able to land and be reviewed alone, with a blocking relation only where one needs another's change. An item that cannot land in parts says why in its body. The orch launch read, oversee.md § 3 Lane directive step 2, sends back an item that still spans several.
• 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; research that is the evidence behind a constraint still in force stays attached to that constraint's issue, and the rest is not kept. 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

To publish artifacts after a run's planned tracker mutations, follow workflows/publish-artifacts.md.

Planning, research, roadmap and audit files are not repository content. A plan or report with no caller-supplied path lives at tmp/plans/<slug>.md (a research report at tmp/plans/<slug>-research.md, a roadmap at tmp/roadmaps/roadmap-<feature>.md), never under a tracked docs/ path; the full rule is agents/planner.md § Plan Artifacts. [RESEARCH_DOCS_PATH], the directory the research workflows name, is tmp/plans/research: a research issue's assets and findings live under tmp/plans/research/<ISSUE_ID>/. Temporary review output belongs under tmp/reviews/.

Where a plan lives and how a reader finds it. An artifact's durable home is its source issue: the issue it already sits on, else the issue it serves, else, when it serves several, the first issue the run creates, or the first open issue it updates in a run that creates none. The local file is a working copy. A reader given a cited path reads that file when it exists in its checkout; otherwise it finds the artifact by the tracker:

• Linear: the link in the read issue's **Artifacts** list, which names the current copy, else an attachment on the source issue, both read through linear SKILL.md § Resolve a cited artifact.
• GitHub Issues: the text in the source issue's body or a comment, read with gh issue view [N] --repo [OWNER/REPO] --json body,comments.
• No tracker: the caller's named path, else tmp/. Nothing makes the file durable, and a missing one is reported missing.