For Troy + co-founder

Our source document for agentic dev

Define the pieces first. Then define how work moves through them.

Tracker Linear is the operational tracker.
Skills Skills define the agent workflows.
Docs Linear is the front door. Repo docs must be linked from Linear.
Merge Agents open PRs. Humans merge.

Linear terms first

What each Linear element is, and how we use it

Read this section before the workflow. Most confusion comes from mixing containers, fields, and states.

Containers: where work lives

Workspace

container
What it isThe Linear account that holds teams, issues, projects, docs, and members.
How we use itOur workspace is vaulted-os. It is the top-level home for Vaulted OS work.

Team

container
What it isA backlog with its own workflow states, cycles, labels, and issues.
How we use itWe use one main team for now: Vaulted OS / VOS.

Initiative

container
What it isA strategic objective above projects.
How we use itUse for broad goals like MVP-1, reliability, launch readiness, or platform hardening.

Project

container
What it isAn epic-sized outcome made of many issues and usually multiple milestones.
How we use itUse Projects for epics. Do not make an epic an executable issue.

Milestone

container
What it isA phase inside a project.
How we use itUse for scoped phases like classification, upload flow, management hub, or launch prep.

Issue

unit
What it isOne executable unit of work.
How we use itUse for bugs, feature slices, tasks, chores, and spikes that can move through the workflow.

Fields and states: how work is sorted and claimed

Status

state
What it isThe current workflow position of an issue.
How we use itTriage -> Backlog -> Todo -> In Progress -> In Review -> Done. Todo means ready.

Assignee

lock
What it isThe person or agent lane currently responsible for the issue.
How we use itUnassigned Todo can be claimed. Assigned work is already owned.

Cycle

focus
What it isA timebox for the work we are actively trying to move.
How we use itAgents should prefer current-cycle Todo work before random backlog work.

Label

axis
What it isA filter used to slice the backlog.
How we use itUse closed taxonomies for type, area, and component. Avoid label sprawl.

Issue type

label
What it isThe kind of work the issue represents: bug, feature, task, chore, spike.
How we use itType decides the Ready Plan form. A feature issue should be an executable slice, not an epic.

Priority

field
What it isRelative urgency or importance of an issue.
How we use itPriority is issue-level. Projects have status and health, not issue priority.

Blocked

state
What it isA dependency, decision, access gap, or missing context prevents progress.
How we use itBlocked work should not enter agent build mode.

Planning elements

Ready Plan

contract
What it isThe issue-body section that makes the issue executable.
How we use itTodo requires a Ready Plan. Missing plan means confirm/shape, not build.

Project brief

doc
What it isThe document explaining the outcome, scope, constraints, and acceptance shape.
How we use itStore in Linear Projects. Link repo docs only when the context belongs beside code.

Project status

project
What it isThe larger delivery state of a project.
How we use itSeparate from issue status. A done issue does not mean the project is done.

Project update

project
What it isA dated health/status note for the project.
How we use itUse for weekly or milestone-level visibility: on track, at risk, blocked, changed scope.

Current decisions

The operating model

This is the shortest version of how the system should work.

01 Human

Intent

Say what matters and why.

02 Linear

Capture

Store the issue, owner, status, and source links.

03 Skill

Shape

Verify scope and write the Ready Plan.

04 Agent

Build

Claim one ready issue and produce evidence.

05 GitHub

Review

Open the PR with proof.

06 Human

Accept

Merge, send back, or update the project.

Tracker rule

  • Linear is the live tracker.
  • Repo docs count only when Linear links to them.

Readiness rule

  • Todo means agent-actionable.
  • Ready Plan is required.

Merge rule

  • Agents can open PRs.
  • Humans merge.

Source of truth

Linear is the front door

Remote agents and teammates start from Linear. Repo docs are references linked from the relevant Project or issue.

Linear

  • Issue state.
  • Assignee.
  • Priority.
  • Blockers.
  • Ready Plan.
  • Links to required repo docs.

Linear Docs / Projects

  • Project brief.
  • Project scope.
  • Milestone definitions.
  • Health updates.
  • Acceptance notes.

Linked repo docs

  • Skills.
  • Runbooks.
  • Code-level decisions.
  • Architecture notes.
  • Implementation details.
Rule: If a remote agent needs it, Linear must point to it. Local-only files and unlinked repo docs are not operational truth.

Readiness

When work becomes executable

Todo is not just a parking state. Todo means an agent can claim and build without inventing scope.

1. CapturedIssue exists in Linear. Usually Triage.
2. ShapedBug verified or feature/task scoped.
3. Planned## Ready Plan exists in issue body.
4. TodoUnblocked, unassigned, ready to claim.
Stop if missingNo plan, blocker, unclear scope, or assigned owner.

Plan type by issue type

bugFix Plan: reproduce, root cause, test, fix.
featureBuild Plan: behavior, criteria, notes.
taskExecution Plan: exact work and verification.
choreChange Plan: maintenance or config work.
spikeResearch Plan: answer a question.
epicUsually a Project, not an issue.
Build eligibility: current Cycle + Todo + Ready Plan + unassigned + not Blocked

Workflow

Who owns each handoff

Read this as ownership, not a table. Each owner has one job at each stage.

Human

decision owner
  • IntakeDescribe the intent.
  • ShapeAnswer scope questions.
  • ReviewMerge, send back, or change direction.

Linear

truth owner
  • CaptureIssue, status, assignee, blocker, cycle.
  • PlanReady Plan lives on the issue.
  • ClosePR link, final status, project update.

Skills

process owner
  • new-issueCreate structured work.
  • confirm-issueVerify and write the Ready Plan.
  • fix-issueBuild exactly one ready issue.

GitHub

evidence owner
  • ClaimBranch or worktree for the issue.
  • BuildCommits and verification.
  • ReviewPR to staging with proof.

Skills

Which skill handles which job

Skills are procedures. They should be narrow enough that agents know when to stop.

start-work

Read the live queue.

Input VOS
Output Queue snapshot
Edits None

new-issue

Create structured Linear work.

Input Idea or bug
Output Issue
State Triage

confirm-issue

Verify, scope, write Ready Plan.

Input Triage
Output Ready Plan
State Todo / Wontfix

fix-issue

Build one ready issue.

Input Todo
Output PR + proof
State In Review

fix-queue

Batch eligible Todo issues.

Input Ready queue
Mode Serial / parallel
Gate Same proof

mayor

Keep the operating loop moving.

Input Linear + git
Output Priorities
Merges Never

mayor-handoff

Checkpoint and reconcile state.

Input Current loop
Output Resume state
Rule Verify live

starting-feature-work

Orient to repo, branch, worktree.

Input Repo
Output Correct branch
Status Needs variant

Projects

Issue done does not mean project done

Projects need their own brief, milestones, status, updates, and acceptance decision.

Project briefWhat outcome are we building?
MilestonesWhat phases define progress?
IssuesWhat executable units move the project?
Project statusIs the larger deliverable on track?
Health updateWhat changed since last review?
AcceptanceHas a human accepted the outcome?
Decision: epics should usually be Linear Projects. Issues should be executable slices.

Sessions

How we run larger agent sessions

Large sessions need focus. The cycle and mayor loop keep agents from scattering across random backlog work.

Open

Pick the work

Use current cycle. Prefer one Project or Milestone plus urgent bug headroom.

Stock

Prepare Todo

Confirm Triage, write Ready Plans, clear blockers.

Run

Dispatch agents

Claim, build, verify, open PRs.

Close

Report reality

Done, carried, blocked, In Review, next-cycle seed.

Open items

Decisions to harden next

These are not final. They should become Linear issues, Linear docs, or repo changes linked from Linear.

SkillsUpdate live skills from legacy ## Fix Plan parsing to ## Ready Plan.repo task
LabelsFinalize type, area, and component taxonomy.Linear admin
ProjectsDefine project statuses and health update cadence.Linear model
DocsCodify the Linear-front-door rule for every project and issue.source truth
CyclesDefine how mayor/sprint agents open and close cycles.workflow
Source document for our agentic dev workflow. Static file: README.html.