opencode-missions 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jared Boynton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# opencode-missions
+
+OpenCode plugin for project-local mission planning, delegated feature execution, structured worker handoffs, and milestone validation. It re-implements the mission lifecycle locally and does not require Droid CLI, Factory runtime files, or any external mission service.
+
+## Install
+
+Add the npm plugin to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-missions"]
+}
+```
+
+OpenCode installs npm plugins automatically with Bun at startup.
+
+Optional agent, command, and skill assets are included under `opencode/`. To install them into the current project:
+
+```bash
+bunx opencode-missions install
+```
+
+That copies:
+
+- `opencode/agents/*` to `.opencode/agents/`
+- `opencode/commands/*` to `.opencode/commands/`
+- `opencode/skills/*` to `.opencode/skills/`
+
+## Usage
+
+After enabling the plugin, use the mission tools directly or install the included `/mission` command and mission agents:
+
+```text
+/mission Build and validate the requested feature through mission mode.
+```
+
+The orchestrator creates a mission workspace, writes mission artifacts and feature plans, starts one worker per feature, receives structured handoffs, injects milestone validators, and refuses completion until implementation and validation work are complete.
+
+Mission state is stored under:
+
+```text
+.opencode/droid-missions/missions/
+```
+
+The storage path intentionally remains stable for compatibility with the recovered mission lifecycle.
+
+## Tools
+
+- `droid_mission_create`
+- `droid_mission_write_artifact`
+- `droid_mission_write_features`
+- `droid_mission_start`
+- `droid_mission_end_feature`
+- `droid_mission_pause`
+- `droid_mission_status`
+- `droid_mission_complete`
+- `droid_mission_dismiss_handoff_items`
+- `droid_mission_list`
+
+## Development
+
+```bash
+bun install
+bun run test
+bun run typecheck
+bun run build
+bun run check:no-droid
+bun run ci
+```
+
+## Release
+
+```bash
+npm version patch
+git push --follow-tags
+npm publish --access public
+```

package/bin/opencode-missions.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+import { cp, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const command = process.argv[2];
+
+if (command !== "install") {
+  console.log("Usage: opencode-missions install [project-directory]");
+  process.exit(command ? 1 : 0);
+}
+
+const packageRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "..",
+);
+const projectRoot = path.resolve(process.argv[3] ?? process.cwd());
+const sourceRoot = path.join(packageRoot, "opencode");
+const targetRoot = path.join(projectRoot, ".opencode");
+
+for (const dir of ["agents", "commands", "skills"]) {
+  await mkdir(path.join(targetRoot, dir), { recursive: true });
+  await cp(path.join(sourceRoot, dir), path.join(targetRoot, dir), {
+    recursive: true,
+    force: true,
+  });
+}
+
+console.log(`Installed opencode-missions assets into ${targetRoot}`);

package/dist/droid-missions/paths.d.ts

@@ -0,0 +1,10 @@
+export declare const STORAGE_DIR: string;
+export declare const MISSIONS_DIR = "missions";
+export declare function missionStorageRoot(projectRoot: string): string;
+export declare function missionsRoot(projectRoot: string): string;
+export declare function sanitizeMissionId(input: string): string;
+export declare function createMissionId(title: string, now: string): string;
+export declare function missionDir(projectRoot: string, missionId: string): string;
+export declare function toMissionRelativePath(relativePath: string): string;
+export declare function assertInside(parent: string, child: string): void;
+export declare function isMissionSystemFile(relativePath: string): boolean;

package/dist/droid-missions/prompts.d.ts

@@ -0,0 +1,16 @@
+import type { MissionFeature, MissionState } from "./types";
+export declare function buildWorkerPrompt(input: {
+    state: MissionState;
+    feature: MissionFeature;
+    missionDir: string;
+    message?: string;
+}): string;
+export declare function buildCompactionContext(input: {
+    state: MissionState;
+    features: MissionFeature[];
+}): string;
+export declare function buildResumePrompt(input: {
+    state: MissionState;
+    feature: MissionFeature;
+    missionDir: string;
+}): string;

package/dist/droid-missions/runner.d.ts

@@ -0,0 +1,28 @@
+import { MissionStore } from "./store";
+import type { EndFeatureRunArgs, MissionFeature, MissionState, StartMissionArgs, StartMissionResult } from "./types";
+type OpenCodeClientLike = {
+    session?: {
+        create?: (options: any) => Promise<unknown>;
+        prompt?: (options: any) => Promise<unknown>;
+        abort?: (options: any) => Promise<unknown>;
+    };
+};
+export declare class MissionRunner {
+    private readonly store;
+    private readonly client;
+    constructor(store: MissionStore, client: OpenCodeClientLike);
+    startMission(args: StartMissionArgs): Promise<StartMissionResult>;
+    endFeatureRun(args: EndFeatureRunArgs): Promise<{
+        feature: MissionFeature;
+        validationInserted: string[];
+    }>;
+    pauseMission(missionId: string, reason?: string, now?: string): Promise<MissionState>;
+    private resumeWorker;
+    completeMission(missionId: string, now?: string): Promise<MissionState>;
+    private injectMilestoneValidators;
+    private injectEligibleMilestoneValidators;
+    private injectValidatorsForMilestone;
+    private getUnresolvedHandoffItems;
+    private getValidationStateBlockers;
+}
+export {};

package/dist/droid-missions/store.d.ts

@@ -0,0 +1,53 @@
+import type { FeatureHandoff, MissionCreateArgs, MissionFeature, MissionSnapshot, MissionState, ProgressEntry, StoredHandoff } from "./types";
+export declare class MissionStore {
+    readonly projectRoot: string;
+    constructor(projectRoot: string);
+    storageRoot(): string;
+    missionsRoot(): string;
+    missionDir(missionId: string): string;
+    createMission(args: MissionCreateArgs): Promise<{
+        dir: string;
+        state: MissionState;
+        features: MissionFeature[];
+    }>;
+    removeMission(missionId: string): Promise<void>;
+    listMissions(): Promise<MissionState[]>;
+    readState(missionId: string): Promise<MissionState>;
+    writeState(state: MissionState): Promise<void>;
+    readFeatures(missionId: string): Promise<MissionFeature[]>;
+    writeFeatureRecords(missionId: string, features: MissionFeature[]): Promise<void>;
+    writeFeatures(missionId: string, inputs: unknown[]): Promise<MissionFeature[]>;
+    listMissionSkills(missionId: string): Promise<Set<string>>;
+    writeArtifact(missionId: string, args: {
+        relativePath: string;
+        content: string;
+    }): Promise<string>;
+    readProgress(missionId: string): Promise<ProgressEntry[]>;
+    appendProgress(missionId: string, entry: ProgressEntry): Promise<void>;
+    readHandoffs(missionId: string): Promise<StoredHandoff[]>;
+    writeHandoffs(missionId: string, handoffs: StoredHandoff[]): Promise<void>;
+    appendHandoff(missionId: string, args: {
+        featureId: string;
+        workerSessionId?: string;
+        successState: StoredHandoff["successState"];
+        returnToOrchestrator: boolean;
+        validatorsPassed?: boolean;
+        commitId?: string;
+        repoPath?: string;
+        handoff: FeatureHandoff;
+        now?: string;
+    }): Promise<StoredHandoff>;
+    appendTranscriptSkeleton(missionId: string, args: {
+        workerSessionId?: string;
+        featureId: string;
+        milestone?: string;
+        skeleton: string;
+        createdAt?: string;
+    }): Promise<void>;
+    readValidationState(missionId: string): Promise<unknown>;
+    dismissHandoffItems(missionId: string, dismissals: Array<{
+        id: string;
+        reason: string;
+    }>, now?: string): Promise<StoredHandoff[]>;
+    snapshot(missionId: string): Promise<MissionSnapshot>;
+}

package/dist/droid-missions/types.d.ts

@@ -0,0 +1,158 @@
+export type MissionStatus = "awaiting_input" | "initializing" | "running" | "paused" | "orchestrator_turn" | "completed";
+export type FeatureStatus = "pending" | "in_progress" | "completed" | "cancelled";
+export type SuccessState = "success" | "partial" | "failure";
+export type ValidationKind = "scrutiny" | "user-testing";
+export type MissionState = {
+    missionId: string;
+    title: string;
+    goal: string;
+    status: MissionStatus;
+    workingDirectory: string;
+    createdAt: string;
+    updatedAt: string;
+    completedAt?: string;
+    activeFeatureId?: string;
+    activeWorkerSessionId?: string;
+    pauseReason?: string;
+    lastMessage?: string;
+};
+export type FeaturePlanInput = {
+    id: string;
+    description: string;
+    skillName: string;
+    milestone: string;
+    preconditions?: string[];
+    expectedBehavior: string;
+    verificationSteps?: string[];
+    fulfills?: string[];
+};
+export type MissionFeature = FeaturePlanInput & {
+    preconditions: string[];
+    verificationSteps: string[];
+    fulfills: string[];
+    status: FeatureStatus;
+    workerSessionId?: string;
+    startedAt?: string;
+    completedAt?: string;
+    isValidation?: boolean;
+    validatesMilestone?: string;
+    validationKind?: ValidationKind;
+};
+export type VerificationCommand = {
+    command: string;
+    exitCode: number;
+    observation: string;
+};
+export type InteractiveCheck = {
+    action: string;
+    observed: string;
+};
+export type HandoffVerification = {
+    commandsRun: VerificationCommand[];
+    interactiveChecks?: InteractiveCheck[];
+};
+export type TestCase = {
+    name: string;
+    verifies: string;
+};
+export type TestFile = {
+    file: string;
+    cases: TestCase[];
+};
+export type HandoffTests = {
+    added: TestFile[];
+    updated?: string[];
+    coverage: string;
+};
+export type DiscoveredIssue = {
+    severity: "blocking" | "non_blocking" | "suggestion";
+    description: string;
+    suggestedFix?: string;
+};
+export type SkillDeviation = {
+    step: string;
+    whatIDidInstead: string;
+    why: string;
+};
+export type SkillFeedback = {
+    followedProcedure: boolean;
+    deviations: SkillDeviation[];
+    suggestedChanges?: string[];
+};
+export type FeatureHandoff = {
+    salientSummary: string;
+    whatWasImplemented: string;
+    whatWasLeftUndone: string;
+    verification: HandoffVerification;
+    tests: HandoffTests;
+    discoveredIssues: DiscoveredIssue[];
+    skillFeedback?: SkillFeedback;
+};
+export type StoredHandoff = FeatureHandoff & {
+    id: string;
+    missionId: string;
+    featureId: string;
+    workerSessionId?: string;
+    successState: SuccessState;
+    returnToOrchestrator: boolean;
+    validatorsPassed?: boolean;
+    commitId?: string;
+    repoPath?: string;
+    handoffFile: string;
+    createdAt: string;
+    dismissedAt?: string;
+    dismissalReason?: string;
+};
+export type ProgressEntry = {
+    type: "mission_accepted" | "mission_paused" | "mission_resumed" | "mission_run_started" | "worker_started" | "worker_selected_feature" | "worker_completed" | "worker_failed" | "worker_paused" | "handoff_items_dismissed" | "milestone_validation_triggered" | "mission_completed" | "features_written" | "artifact_written";
+    at: string;
+    missionId: string;
+    featureId?: string;
+    workerSessionId?: string;
+    summary?: string;
+    details?: Record<string, unknown>;
+};
+export type MissionSnapshot = {
+    dir: string;
+    state: MissionState;
+    features: MissionFeature[];
+    handoffs: StoredHandoff[];
+    progress: ProgressEntry[];
+};
+export type MissionCreateArgs = {
+    missionId?: string;
+    title: string;
+    goal: string;
+    workingDirectory?: string;
+    now?: string;
+};
+export type StartMissionArgs = {
+    missionId: string;
+    parentSessionId?: string;
+    message?: string;
+    resumeWorkerSessionId?: string;
+    restartFeature?: boolean;
+    now?: string;
+};
+export type StartMissionResult = {
+    started: boolean;
+    completed: boolean;
+    missionId: string;
+    featureId?: string;
+    workerSessionId?: string;
+    blockedReason?: string;
+    systemMessage: string;
+};
+export type EndFeatureRunArgs = {
+    missionId: string;
+    featureId: string;
+    workerSessionId?: string;
+    successState: SuccessState;
+    returnToOrchestrator?: boolean;
+    validatorsPassed?: boolean;
+    codeChanged?: boolean;
+    commitId?: string;
+    repoPath?: string;
+    handoff: FeatureHandoff;
+    now?: string;
+};

package/dist/droid-missions/validation.d.ts

@@ -0,0 +1,4 @@
+import type { MissionFeature } from "./types";
+export declare function validateFeaturePlans(inputs: unknown[], skillNames: Set<string>): MissionFeature[];
+export declare function validateArtifactPath(relativePath: string): string;
+export declare function missionSkillExists(missionDir: string, skillName: string): Promise<boolean>;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin } from "@opencode-ai/plugin";
+export declare const DroidMissionsPlugin: Plugin;
+export default DroidMissionsPlugin;