@voidlabs.gg/voidshift-agents 0.0.0-stage → 0.4.1

package/dist/workflow.d.ts

@@ -0,0 +1,52 @@
+export declare const PLAN_HEADING = "## Plan";
+export declare const LABELS: {
+    stage: Record<string, string>;
+    changes: string;
+    verified: string;
+    parked: string;
+    version: (round: number) => string;
+    working: string;
+};
+export declare const isVersionLabel: (name: string) => boolean;
+export declare const isRoundLabel: (name: string) => boolean;
+export declare const isStatusLabel: (name: string) => boolean;
+export declare function stageLabels(current: string[], trigger: string, stage: string, round?: number): string[];
+export type Verdict = 'SHIP' | 'FIX' | 'SKIP';
+export interface StepResult {
+    step: string;
+    verdict: Verdict;
+    report: string;
+}
+export declare function parseVerdict(output: string): Verdict;
+export type DevResult = {
+    status: 'done';
+} | {
+    status: 'blocked';
+    reason: string;
+};
+export declare function parseDevResult(output: string): DevResult;
+export declare function qaPassed(results: StepResult[]): boolean;
+export declare function findingsFor(results: StepResult[]): string;
+export declare function latestPlan(comments: {
+    body: string;
+    createdAt: string;
+}[]): string | null;
+export declare function skillBody(markdown: string): string;
+export interface PromptInput {
+    skill: string;
+    card: {
+        identifier: string;
+        title: string;
+        description?: string;
+        url?: string;
+    };
+    plan: string;
+    base: string;
+    round: number;
+    findings?: string;
+    extra?: string;
+}
+export declare function buildPrompt(p: PromptInput): string;
+export declare function verdictBlock<T extends string>(steps: T[], i: number, isVerdict: (s: T) => boolean): [number, number];
+export declare function fixTarget<T extends string>(steps: T[], blockStart: number, isProducer: (s: T) => boolean): number;
+export declare function planBody(output: string): string;

package/dist/workflow.js

@@ -0,0 +1,111 @@
+// The build workflow and the pure decisions around it. The runner does the I/O;
+// everything here is testable without Linear, git or an agent.
+export const PLAN_HEADING = '## Plan';
+// Plans posted before 0.1.5 used this heading; still read them.
+const OLD_PLAN_HEADING = '## VoidShift plan';
+// A card carries at most two VoidShift labels: one stage label (which agent has
+// it, or how it ended) and one version label (which round it is on).
+export const LABELS = {
+    stage: {
+        'vs-plan': 'vs-planning',
+        'vs-plan-review': 'vs-plan-review',
+        'vs-publish': 'vs-publish',
+        'vs-dev': 'vs-dev',
+        'vs-qa': 'vs-qa',
+    },
+    changes: 'vs-changes-requested',
+    verified: 'vs-qa-verified',
+    parked: 'vs-parked',
+    version: (round) => `vs-v${round}`,
+    // Labels from earlier runners, still cleaned off cards.
+    working: 'vs-working',
+};
+const STAGE_NAMES = new Set([...Object.values(LABELS.stage), LABELS.changes, LABELS.verified, LABELS.parked, LABELS.working]);
+export const isVersionLabel = (name) => /^vs-v\d+$/.test(name);
+// Round labels earlier runners stacked up, one per step and round.
+export const isRoundLabel = (name) => /^vs-(plan|review|dev|qa)-v\d+$/.test(name);
+export const isStatusLabel = (name) => STAGE_NAMES.has(name) || isVersionLabel(name) || isRoundLabel(name);
+// The card's labels with every VoidShift label (and the trigger) replaced by
+// one stage label and, when given, one version label.
+export function stageLabels(current, trigger, stage, round) {
+    const kept = current.filter((l) => l !== trigger && !isStatusLabel(l));
+    return [...new Set([...kept, stage, ...(round ? [LABELS.version(round)] : [])])];
+}
+// The last "VERDICT: X" line wins; anything unreadable counts as FIX so a
+// confused agent never waves a change through.
+export function parseVerdict(output) {
+    const matches = [...output.matchAll(/^\s*VERDICT:\s*(SHIP|FIX|SKIP)\b/gim)];
+    const last = matches.at(-1)?.[1]?.toUpperCase();
+    return last === 'SHIP' || last === 'SKIP' ? last : 'FIX';
+}
+export function parseDevResult(output) {
+    const matches = [...output.matchAll(/^\s*RESULT:\s*(DONE|BLOCKED)\b\s*(.*)$/gim)];
+    const last = matches.at(-1);
+    if (last?.[1]?.toUpperCase() === 'DONE')
+        return { status: 'done' };
+    if (last?.[1]?.toUpperCase() === 'BLOCKED')
+        return { status: 'blocked', reason: last[2]?.trim() || 'no reason given' };
+    return { status: 'blocked', reason: 'the dev agent ended without a RESULT line' };
+}
+export function qaPassed(results) {
+    return results.every((r) => r.verdict !== 'FIX');
+}
+// What the dev agent sees on the next round.
+export function findingsFor(results) {
+    const failed = results.filter((r) => r.verdict === 'FIX');
+    if (failed.length === 1)
+        return failed[0].report.trim();
+    return failed.map((r) => `### ${r.step}\n\n${r.report.trim()}`).join('\n\n');
+}
+export function latestPlan(comments) {
+    const headingOf = (body) => {
+        const first = body.trimStart().split('\n', 1)[0].trim();
+        return first === PLAN_HEADING || first === OLD_PLAN_HEADING ? first : null;
+    };
+    const plans = comments
+        .filter((c) => headingOf(c.body))
+        .sort((a, b) => Date.parse(a.createdAt) - Date.parse(b.createdAt));
+    const last = plans.at(-1);
+    return last ? last.body.trimStart().slice(headingOf(last.body).length).trim() : null;
+}
+// Strip the frontmatter from a SKILL.md so the body can be inlined.
+export function skillBody(markdown) {
+    return markdown.replace(/^---\n[\s\S]*?\n---\n/, '').trim();
+}
+export function buildPrompt(p) {
+    const parts = [
+        skillBody(p.skill),
+        '---',
+        `# Card ${p.card.identifier}: ${p.card.title}`,
+        p.card.url ? p.card.url : '',
+        p.card.description?.trim() || '(no description)',
+        '# Plan',
+        p.plan,
+        `# Round\n\nRound ${p.round}. Base branch: \`${p.base}\`.`,
+    ];
+    if (p.findings)
+        parts.push('# Findings to address', p.findings);
+    if (p.extra)
+        parts.push(p.extra);
+    return parts.filter(Boolean).join('\n\n');
+}
+// Consecutive verdict steps run as one block so every finding comes back at
+// once. Returns [start, end) of the block that starts at `i`.
+export function verdictBlock(steps, i, isVerdict) {
+    let end = i;
+    while (end < steps.length && isVerdict(steps[end]))
+        end++;
+    return [i, end];
+}
+// Where a failed check sends the work: the nearest earlier step that produces
+// something. -1 means nothing to send it back to.
+export function fixTarget(steps, blockStart, isProducer) {
+    for (let j = blockStart - 1; j >= 0; j--)
+        if (isProducer(steps[j]))
+            return j;
+    return -1;
+}
+// Plan output minus the trailing RESULT line, ready to post.
+export function planBody(output) {
+    return output.replace(/^\s*RESULT:.*$/gim, '').trim();
+}

package/pack/vs-dev/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: vs-dev
+description: Implement a published plan on its branch. Run by the background runner, not by hand.
+---
+
+# Implement a plan
+
+You implement one Linear card on its own branch, unattended. The runner gives
+you the card, the plan and, on later rounds, the QA findings to fix. Nobody
+will answer questions; make the call the plan and the code support.
+
+## Work
+
+1. **Read before you write.** Read every file the plan names, plus the code
+   around it, so the change matches the style already there.
+2. **Follow the plan.** Do the numbered steps in order. Where the plan is
+   wrong against the code, follow the code, do the smallest thing that meets
+   the card, and note it in your report.
+3. **On a fix round**, address every QA finding. When CI failed, read each
+   failed check's log first: `gh run view --job <job id from its link>
+   --log-failed`. Only fix failures your change caused; if a check fails the
+   same way on the base branch, say so in your report instead. Where a finding is wrong,
+   leave the code and say why in one line, with the file and line.
+4. **Tests.** Add or update the tests the plan lists. Run the project's
+   typecheck, lint and tests that apply, and fix what you broke.
+5. **Commit** on the current branch with short messages in the repo's style.
+   Do not push and do not open a pull request; the runner does both.
+
+## Never
+
+- Run migrations, backfills or scripts against any shared or remote database.
+- Change CI, deploy or environment configuration unless the plan says so.
+- Touch files outside the repository.
+- Put ticket ids in code comments, or use em dashes or en dashes.
+
+## Report
+
+Short and plain, for a reviewer who has not seen the plan:
+
+- First line: what you did, in one sentence.
+- Up to 3 lines on anything that differs from the plan and why.
+- One line on checks: which ran, pass or fail.
+
+The final line is exactly one of:
+
+```
+RESULT: DONE
+RESULT: BLOCKED <one line reason>
+```
+
+BLOCKED only when the card cannot be done without a human decision.

package/pack/vs-plan/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: vs-plan
+description: Plan a Linear card against this repo before any code is written. Use when the user asks to plan a card, plan a ticket, or runs /vs-plan with a card id like ENG-123.
+---
+
+# Plan a card
+
+You are planning one Linear card against whatever repository is open, with
+the developer beside you. This agent is installed once per machine and works
+in any repo; it never adds files to the repo. The plan becomes the spec a dev
+agent executes later, unattended, without rediscovering what you found. Write
+for that agent. A human should get the whole picture in under a minute.
+
+You read code. You do not edit it.
+
+## 1. Load the card
+
+Fetch the card through the Linear connection: title, description, comments,
+labels. If Linear is not connected, stop and tell the developer to connect it.
+Comments that answer earlier questions are decisions; build on them.
+
+Plan drafts live outside every repo, at `~/.config/voidshift/plans/<CARD>.md`.
+If that file exists, this is a revision: read it first and
+keep what still holds.
+
+## 2. Check the card against the code
+
+Cards are written from memory. Confirm every factual claim before planning:
+something called missing may be mostly built, a "bug" may be configuration, a
+field may not exist, the fix may already be on the base branch. Where the card
+is wrong, say so plainly. If it is already done, the plan is the proof.
+
+## 3. Think through six angles
+
+Work through each. Write only what applies; "none" is a fine answer.
+
+1. **Data and schema.** Tables, collections, fields, indexes, validators. What
+   old records look like after the change. Any migration or backfill is a
+   human step, never an agent step.
+2. **UI and UX.** The experience end to end: every screen where the value is
+   shown or edited, empty, loading and error states, mobile, keyboard,
+   accessibility, copy.
+3. **Backend.** Routes, services, jobs, permissions on every path touched,
+   other clients of the same endpoint, concurrency and idempotency, cost and
+   performance on real data sizes.
+4. **Reuse.** The existing helper, component or pattern to follow so the
+   change reads like it was always there. A rule that exists in three places
+   gets one home, not a fourth copy.
+5. **Solidify what is there.** Small fixes to the current UI and UX on the
+   surfaces this card already touches, which make the result feel finished.
+   Keep them small and on those surfaces only.
+6. **Nearby bugs.** Defects in the code around this change that could break it
+   or that it would make worse. Fix the ones on the path; list the rest under
+   Out of scope.
+
+Name what you searched for, so a reviewer can repeat it.
+
+## 4. Ask, then write
+
+Ask the developer only what blocks the plan and is not answered by the repo or
+the card, one line per question, each with the option you would pick. Where a
+sensible default exists, pick it and say so.
+
+Then write the plan to `~/.config/voidshift/plans/<CARD>.md` (create the
+folder if needed). Never post to Linear from this agent; `vs-publish` does that.
+
+## 5. Get it reviewed before showing it
+
+The developer should only ever see a plan that has already been reviewed.
+
+1. Run the `vs-plan-review` checks as a separate pass with fresh eyes: in Claude
+   Code, hand them to a subagent with the card id and the plan file path; where
+   no subagent is available, re-read the plan cold and apply that checklist
+   yourself.
+2. If it says FIX, fix the plan file for every finding that is right. Where a
+   finding is wrong, keep the plan and note why in one line.
+3. Repeat until it says SHIP, at most 3 rounds. If it still says FIX after 3,
+   stop and show what is left as decisions for the developer.
+
+Then show the developer the short version below.
+
+## What you show the developer
+
+The plan file holds the detail. In the chat, keep it short and plain:
+
+- First line: `Reviewed: ready after N rounds.` or `Reviewed: N things still need your call.`
+- One or two lines: what the card really needs, and what it got wrong.
+- The steps, one short sentence each, no file paths.
+- Any decision only they can make, as a question with your pick.
+- The path to the plan file, and that `/vs-publish <CARD>` hands it over.
+
+## Plan shape (the file)
+
+Start straight at Understanding. Do not repeat the card id or title; the card
+already shows them.
+
+Length follows the change: under 350 words for a small one, never padded.
+
+**Understanding.** Two to four sentences: what the card asks, what it got
+wrong, which reading you chose.
+
+**Surfaces.** Each file that changes as `path/to/file.ts:123` and why. One
+line on what you searched and ruled out.
+
+**Approach.** Numbered steps concrete enough to execute without judgment, each
+naming the pattern to follow. One line on the alternative not taken.
+
+**Six angles.** One short line per angle that applies.
+
+**Tests.** For each behaviour that changes, the test that fails before and
+passes after. Tests that encode the old behaviour and must change.
+
+**Done when.** Checkable criteria plus the commands that must pass, and
+anything a human must click.
+
+**Human steps.** Migrations, backfills, environment variables, releases.
+"None" if none.
+
+**Out of scope.** Worth doing, not asked for, one line each.
+
+## Rules
+
+- No ticket ids in code comments.
+- No em dashes or en dashes.
+- No narration of process. State findings.
+
+## When you run inside a workflow
+
+The card is in the prompt and nobody can answer. Skip the Linear fetch, the
+questions and step 5 (the workflow runs its own review): pick the sensible default for anything open and state it under
+Understanding. Do not write a plan file. Return the plan in the shape above as
+your final message, then one last line, exactly one of:
+
+```
+RESULT: DONE
+RESULT: BLOCKED <one line reason>
+```
+
+If findings from a plan review are in the prompt, revise the plan to address
+every one, or say in one line why a finding is wrong.

package/pack/vs-plan-review/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: vs-plan-review
+description: Review a plan against the code before it is published. Use when the user asks to review a plan, check a plan, or runs /vs-plan-review with a card id.
+---
+
+# Review a plan
+
+You check a plan written by `vs-plan` for one Linear card. Your job is to find
+what the plan got wrong or missed before a dev agent spends a run on it. You
+read code. You do not edit code or the plan.
+
+## Inputs
+
+- The plan at `~/.config/voidshift/plans/<CARD>.md`.
+- The card, through the Linear connection: description and comments.
+- The open repository.
+
+## Check
+
+1. **Claims.** Every file, function, field and line the plan cites exists and
+   says what the plan says. Re-run the searches the plan names.
+2. **Missed surfaces.** Search for the thing the card is about yourself. Any
+   reader, writer, screen, export, validator, permission or test the plan
+   left out is a finding.
+3. **Six angles.** Data and schema, UI and UX, backend, reuse, solidifying
+   what is there, nearby bugs. Flag any angle the plan skipped that applies.
+4. **Executability.** Could an agent follow each step without judgment? Vague
+   steps ("update the UI as needed") are findings.
+5. **Done when.** Every criterion is checkable and covers what the card asks.
+6. **Scope.** Work the card did not ask for belongs under Out of scope.
+
+Do not flag style preferences or restate the plan. Each finding must change
+what gets built.
+
+## Output
+
+Write for a busy developer: the answer first, plain words, no file paths in the
+main points.
+
+1. First line: `Ready to build.` or `Not ready yet. N things to fix:`
+2. The findings that change what gets built, most important first, at most 5,
+   one short plain line each: what is wrong and what to do about it.
+3. Everything smaller in one line: `Minor: ...`.
+4. A short `Details` section: for each finding, the file and line that proves it.
+5. Last line, exactly one of:
+
+```
+VERDICT: SHIP
+VERDICT: FIX
+```
+
+SHIP means a dev agent can execute the plan as written. Offer to apply the
+fixes to the plan file.
+
+## Rules
+
+- No em dashes or en dashes.
+- No narration of process. State findings.
+
+## When you run inside a workflow
+
+The card and the plan are in the prompt; read them there instead of the plan
+file and Linear. Do not offer to edit anything. End with the VERDICT line.

package/pack/vs-publish/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: vs-publish
+description: Publish an approved plan to its Linear card and hand the card to the background agents. Use when the user says the plan is approved, asks to publish a plan, or runs /vs-publish with a card id.
+---
+
+# Publish a plan
+
+The developer has reviewed and approved the plan for one card. Hand it over to
+the background agents. Do every step; stop and report if one fails.
+
+1. **Read the plan** at `~/.config/voidshift/plans/<CARD>.md`. If it is
+   missing, stop and say so.
+2. **Post it to the card** through the Linear connection as one comment whose
+   first line is exactly:
+
+   ```
+   ## Plan
+   ```
+
+   followed by the plan unchanged. The background agents find the plan by
+   that heading, newest first.
+3. **Create the branch** the card names (Linear's branch name for the card),
+   from the project's base branch without switching the developer's checkout.
+   The base is the `base` of this repo's project in
+   `~/.config/voidshift/agents/config.json`, or the repo's default branch when
+   it has none:
+
+   ```
+   git fetch origin
+   git branch <branch> origin/<base>
+   git push -u origin <branch>
+   ```
+
+   If the branch already exists on origin, leave it.
+4. **Hand it over.** Add the label `vs-plan` to the card and make sure the card
+   is assigned to the developer. That label is what the background agents
+   pick up.
+5. **Clean up.** Delete the local plan file.
+6. **Report** in one line: the card, the branch, and that the agents pick it
+   up within about a minute if the runner is on.
+
+## Rules
+
+- Never edit the plan while publishing.
+- No em dashes or en dashes.

package/pack/vs-qa/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: vs-qa
+description: QA a branch against its card and plan, CI first, then code review, then a usability check in a headless browser. Use when the user asks to QA a branch or card, or runs /vs-qa with a card id.
+---
+
+# QA
+
+You check the change on the current branch for one Linear card. Three checks,
+in order. You read code and run commands; you do not edit code.
+
+## 1. CI
+
+If the prompt already reports CI as passed, move on. Otherwise run
+`gh pr checks` for the branch. Failing checks are findings; stop here and
+report them, since review on a red build wastes everyone's time.
+
+## 2. Code review
+
+1. **Diff.** `git diff <base>...HEAD` is the whole change. Read it fully, and
+   the surrounding code for every hunk.
+2. **Against the card.** Every acceptance point in the card and every Done
+   when criterion in the plan is met. Check exemptions and special cases in
+   the code against the card's wording: a carve-out the card did not allow is
+   a finding.
+3. **Correctness.** Logic errors, missed callers, broken old records,
+   permissions, error and empty states, races, anything that would fail in
+   production.
+4. **Surfaces.** Search for other readers and writers of what changed. A
+   surface the change should have updated and did not is a finding.
+5. **Tests.** The changed behaviour has tests that would fail without it. Run
+   the project's typecheck and tests if they exist and report failures.
+6. **Fit.** The change follows the patterns around it, with no duplicated
+   rules, no `any`, no dead code, no ticket ids in comments.
+
+Only report findings that change behaviour or would block a careful reviewer.
+No style nits.
+
+## 3. Usability check
+
+Only if the change has a user-facing surface.
+
+1. Find how the project runs locally (README, `package.json` scripts). If it
+   needs services you cannot start (databases, other apps, secrets), skip this
+   check and say why in one line.
+2. Start it from this checkout on a free port, in the background, and wait
+   until it answers.
+3. Drive a headless browser with Playwright (for example a short script run
+   with `npx playwright`). Never open a visible window. For each flow in the
+   plan's Done when: open the page, do the clicks and typing, check what is on
+   screen. Note console errors, failed requests, layout that breaks at a phone
+   width, and anything unreadable.
+4. Stop everything you started.
+
+## Output
+
+Write for a busy developer: the answer first, plain words.
+
+1. First line: `Passed.` or `Changes needed: N things.`
+2. One line per check: CI, Code review, Usability, each passed, failed or
+   skipped (with why).
+3. The problems, most important first, at most 5, one short plain line each:
+   what is wrong and what to do.
+4. Everything smaller in one line: `Minor: ...`.
+5. A short `Details` section with the file and line for each problem.
+6. Last line, exactly one of:
+
+```
+VERDICT: SHIP
+VERDICT: FIX
+```
+
+No em dashes or en dashes.

package/package.json

@@ -1,6 +1,52 @@
 {
   "name": "@voidlabs.gg/voidshift-agents",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.4.1",
+  "description": "Agents for Claude Code and Codex that plan, build and QA Linear cards, chained and run in the background.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/EratosVoid/voidshift.git",
+    "directory": "tools/agents"
+  },
+  "homepage": "https://voidlabs.gg",
+  "bugs": {
+    "url": "https://github.com/EratosVoid/voidshift/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "agents",
+    "linear",
+    "cli",
+    "macos"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "pack",
+    "LICENSE",
+    "README.md"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.ts",
+    "prepublishOnly": "rm -rf dist && tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.0",
+    "typescript": "^5.9.0"
+  }
+}