opencode-agile-agent 1.0.4 → 1.2.1

package/templates/.opencode/plugins/session-artifacts.ts

@@ -0,0 +1,611 @@
+import { tool } from "@opencode-ai/plugin"
+import { execFileSync } from "child_process"
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs"
+import { dirname, join } from "path"
+import YAML from "yaml"
+
+type StatusState = "brainstorm" | "planning" | "implementation" | "verification" | "review" | "done" | "blocked"
+
+type StatusDocument = {
+  feature: string
+  owner: string
+  handoff_to: string
+  stage: StatusState
+  status: StatusState
+  summary: string
+  next_step: string
+  updated_at: string
+  approved_scope: string[]
+  open_questions: string[]
+  risks: string[]
+  blockers: string[]
+  files_of_interest: string[]
+  changed_files: string[]
+}
+
+type PluginContext = {
+  directory: string
+  client: any
+}
+
+const FEATURE_ROOT = ["artifacts", "features"]
+const ACTIVE_FEATURE_FILE = ["artifacts", "active-feature.txt"]
+const ARCHIVE_ROOT = ["archive"]
+const TEMPLATE_ROOT = ["templates"]
+
+const DEFAULT_STATUS = (feature: string): StatusDocument => ({
+  feature,
+  owner: "feature-lead",
+  handoff_to: "context-gatherer",
+  stage: "brainstorm",
+  status: "brainstorm",
+  summary: "New feature conversation started.",
+  next_step: "Clarify the request and decide whether to promote it into planning.",
+  updated_at: new Date().toISOString(),
+  approved_scope: [],
+  open_questions: [],
+  risks: [],
+  blockers: [],
+  files_of_interest: [],
+  changed_files: [],
+})
+
+const slugify = (value: string) =>
+  value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "active-feature"
+
+const ensureDir = (path: string) => {
+  if (!existsSync(path)) mkdirSync(path, { recursive: true })
+}
+
+const readText = (path: string) => (existsSync(path) ? readFileSync(path, "utf8") : "")
+
+const writeText = (path: string, content: string) => {
+  ensureDir(dirname(path))
+  writeFileSync(path, content)
+}
+
+const appendJsonLine = (path: string, record: Record<string, unknown>) => {
+  const current = readText(path)
+  writeText(path, `${current}${JSON.stringify(record)}\n`)
+}
+
+const templatePath = (ctx: PluginContext, file: string) => join(ctx.directory, ...TEMPLATE_ROOT, file)
+const featureRoot = (ctx: PluginContext) => join(ctx.directory, ...FEATURE_ROOT)
+const featurePath = (ctx: PluginContext, feature: string) => join(featureRoot(ctx), feature)
+const archiveRoot = (ctx: PluginContext) => join(ctx.directory, ...ARCHIVE_ROOT)
+const activeFeatureFile = (ctx: PluginContext) => join(ctx.directory, ...ACTIVE_FEATURE_FILE)
+const statusPath = (ctx: PluginContext, feature: string) => join(featurePath(ctx, feature), "status.yaml")
+const handoffPath = (ctx: PluginContext, feature: string) => join(featurePath(ctx, feature), "handoff", "latest.md")
+const notesPath = (ctx: PluginContext, feature: string) => join(featurePath(ctx, feature), "notes.md")
+const archiveSummaryPath = (ctx: PluginContext, feature: string) => join(archiveRoot(ctx), `${feature}.md`)
+
+const resolveCurrentFeature = (ctx: PluginContext) => {
+  const current = readText(activeFeatureFile(ctx)).trim()
+  if (current) return current
+
+  const root = featureRoot(ctx)
+  if (!existsSync(root)) return ""
+  const dirs = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory())
+  return dirs[0]?.name ?? ""
+}
+
+const saveCurrentFeature = (ctx: PluginContext, feature: string) => {
+  writeText(activeFeatureFile(ctx), `${feature}\n`)
+}
+
+const ensureFeatureScaffold = (ctx: PluginContext, feature: string) => {
+  const root = featurePath(ctx, feature)
+  ensureDir(root)
+  ensureDir(join(root, "handoff"))
+  ensureDir(join(root, "sessions"))
+  ensureDir(join(root, "evidence"))
+
+  const templateFiles = [
+    ["brief.template.md", "brief.md"],
+    ["spec.template.md", "spec.md"],
+    ["task.template.md", "task.md"],
+    ["notes.template.md", "notes.md"],
+  ] as const
+
+  for (const [template, target] of templateFiles) {
+    const nextPath = join(root, target)
+    if (!existsSync(nextPath)) writeText(nextPath, readText(templatePath(ctx, template)))
+  }
+
+  if (!existsSync(statusPath(ctx, feature))) {
+    saveStatus(ctx, feature, DEFAULT_STATUS(feature))
+  }
+}
+
+const loadStatus = (ctx: PluginContext, feature: string): StatusDocument => {
+  ensureFeatureScaffold(ctx, feature)
+  const parsed = YAML.parse(readText(statusPath(ctx, feature))) as Partial<StatusDocument> | null
+  return {
+    ...DEFAULT_STATUS(feature),
+    ...(parsed ?? {}),
+    feature,
+  }
+}
+
+const saveStatus = (ctx: PluginContext, feature: string, status: StatusDocument) => {
+  writeText(statusPath(ctx, feature), YAML.stringify(status))
+}
+
+const unique = (values: string[]) => [...new Set(values.filter(Boolean))]
+
+const sectionList = (items: string[]) => (items.length ? items.map((item) => `- ${item}`).join("\n") : "- None")
+
+const buildHandoff = (status: StatusDocument, target: string) => {
+  const lines = [
+    "# Handoff",
+    "",
+    `- Feature: ${status.feature}`,
+    `- Stage: ${status.stage}`,
+    `- Requested owner: ${target}`,
+    `- Current owner: ${status.owner}`,
+    `- Summary: ${status.summary}`,
+    `- Next step: ${status.next_step}`,
+    "",
+    "## Approved Scope",
+    sectionList(status.approved_scope),
+    "",
+    "## Open Questions",
+    sectionList(status.open_questions),
+    "",
+    "## Risks",
+    sectionList(status.risks),
+    "",
+    "## Blockers",
+    sectionList(status.blockers),
+    "",
+    "## Files Of Interest",
+    sectionList(status.files_of_interest),
+    "",
+    "## Changed Files",
+    sectionList(status.changed_files),
+  ]
+  return lines.join("\n")
+}
+
+const refreshHandoff = (ctx: PluginContext, feature: string, target: string, status: StatusDocument) => {
+  writeText(handoffPath(ctx, feature), `${buildHandoff(status, target)}\n`)
+}
+
+const updateNotes = (ctx: PluginContext, feature: string, label: string, items: string[]) => {
+  if (!items.length) return
+  const path = notesPath(ctx, feature)
+  const current = readText(path)
+  const block = [``, `## ${label}`, ...items.map((item) => `- ${item}`)].join("\n")
+  writeText(path, `${current.trimEnd()}\n${block}\n`)
+}
+
+const fileContents = (ctx: PluginContext, feature: string, name: string) => {
+  const path = join(featurePath(ctx, feature), name)
+  return readText(path).trim()
+}
+
+const specAcceptanceCriteria = (ctx: PluginContext, feature: string) => {
+  const spec = fileContents(ctx, feature, "spec.md")
+  if (!spec) return "Acceptance criteria not written yet."
+  const match = spec.match(/## Acceptance Criteria\s*([\s\S]*?)(\n## |$)/)
+  return match?.[1]?.trim() || "Acceptance criteria not written yet."
+}
+
+const reviewPacket = (ctx: PluginContext, feature: string) => {
+  const status = loadStatus(ctx, feature)
+  const lines = [
+    "# Review Packet",
+    "",
+    `- Feature: ${status.feature}`,
+    `- Stage: ${status.stage}`,
+    `- Summary: ${status.summary}`,
+    `- Next step: ${status.next_step}`,
+    "",
+    "## Approved Scope",
+    sectionList(status.approved_scope),
+    "",
+    "## Acceptance Criteria",
+    specAcceptanceCriteria(ctx, feature),
+    "",
+    "## Risks",
+    sectionList(status.risks),
+    "",
+    "## Changed Files",
+    sectionList(status.changed_files),
+  ]
+  return lines.join("\n")
+}
+
+const archiveSummary = (ctx: PluginContext, feature: string, finalSummary: string) => {
+  const status = loadStatus(ctx, feature)
+  const lines = [
+    `# ${feature}`,
+    "",
+    `- Archived: ${new Date().toISOString()}`,
+    `- Final stage: ${status.stage}`,
+    `- Owner: ${status.owner}`,
+    `- Summary: ${status.summary}`,
+    "",
+    "## What Was Done",
+    finalSummary.trim(),
+    "",
+    "## Approved Scope",
+    sectionList(status.approved_scope),
+    "",
+    "## Changed Files",
+    sectionList(status.changed_files),
+    "",
+    "## Risks Or Follow-Up",
+    sectionList(unique([...status.risks, ...status.blockers, ...status.open_questions])),
+  ]
+  return lines.join("\n") + "\n"
+}
+
+const runGit = (ctx: PluginContext, args: string[]) => {
+  try {
+    return execFileSync("git", ["-C", ctx.directory, ...args], { encoding: "utf8" }).trim()
+  } catch {
+    return ""
+  }
+}
+
+const repoDelta = (ctx: PluginContext, feature: string) => {
+  const status = loadStatus(ctx, feature)
+  const porcelain = runGit(ctx, ["status", "--porcelain"])
+  const trackedArtifact = unique([...status.changed_files, ...status.files_of_interest])
+
+  const gitChanged = unique(
+    porcelain
+      .split(/\r?\n/)
+      .map((line) => line.trimEnd())
+      .filter(Boolean)
+      .map((line) => line.slice(3).replace(/\\/g, "/")),
+  )
+
+  const artifactOnly = trackedArtifact.filter((file) => !gitChanged.includes(file.replace(/\\/g, "/")))
+  const gitOnly = gitChanged.filter((file) => !trackedArtifact.includes(file))
+  const clean = artifactOnly.length === 0 && gitOnly.length === 0
+
+  const lines = [
+    "# Repo Delta",
+    "",
+    `- Feature: ${feature}`,
+    `- Clean match: ${clean ? "yes" : "no"}`,
+    "",
+    "## Artifact Files",
+    sectionList(trackedArtifact),
+    "",
+    "## Git Changed Files",
+    sectionList(gitChanged),
+    "",
+    "## Artifact Only",
+    sectionList(artifactOnly),
+    "",
+    "## Git Only",
+    sectionList(gitOnly),
+  ]
+
+  return lines.join("\n")
+}
+
+const archiveReadiness = (ctx: PluginContext, feature: string) => {
+  ensureFeatureScaffold(ctx, feature)
+  const status = loadStatus(ctx, feature)
+  const required = ["brief.md", "spec.md", "task.md", "notes.md", "status.yaml"]
+  const missing = required.filter((file) => !existsSync(join(featurePath(ctx, feature), file)))
+  const issues = [
+    ...(missing.length ? [`Missing files: ${missing.join(", ")}`] : []),
+    ...(status.status !== "done" ? [`status.yaml.status must be done, got ${status.status}`] : []),
+    ...(!status.summary ? ["summary is empty"] : []),
+    ...(!status.next_step ? ["next_step is empty"] : []),
+  ]
+  return issues.length ? `NOT READY\n${issues.map((issue) => `- ${issue}`).join("\n")}` : `READY\n- ${feature} can be archived.`
+}
+
+const createCurrentTool = (ctx: PluginContext) =>
+  tool({
+    description: "Read the current active feature artifact and return the live execution state.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      saveCurrentFeature(ctx, feature)
+      const status = loadStatus(ctx, feature)
+      return [
+        `Feature: ${status.feature}`,
+        `Stage: ${status.stage}`,
+        `Status: ${status.status}`,
+        `Owner: ${status.owner}`,
+        `Next: ${status.next_step}`,
+        `Summary: ${status.summary}`,
+        `Files of interest: ${status.files_of_interest.join(", ") || "none"}`,
+        `Changed files: ${status.changed_files.join(", ") || "none"}`,
+      ].join("\n")
+    },
+  })
+
+const createHandoffTool = (ctx: PluginContext) =>
+  tool({
+    description: "Generate the canonical handoff packet for a target subagent.",
+    args: {
+      target: tool.schema.string().describe("Target subagent name."),
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      saveCurrentFeature(ctx, feature)
+      const status = loadStatus(ctx, feature)
+      refreshHandoff(ctx, feature, args.target, status)
+      appendJsonLine(join(featurePath(ctx, feature), "evidence", "handoffs.jsonl"), {
+        timestamp: new Date().toISOString(),
+        feature,
+        target: args.target,
+        stage: status.stage,
+      })
+      return readText(handoffPath(ctx, feature))
+    },
+  })
+
+const createSectionTool = (ctx: PluginContext) =>
+  tool({
+    description: "Read one planning artifact section without loading the full feature bundle.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+      section: tool.schema.enum(["brief", "spec", "task", "notes", "status"]).describe("Artifact section to read."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      const map: Record<string, string> = {
+        brief: "brief.md",
+        spec: "spec.md",
+        task: "task.md",
+        notes: "notes.md",
+        status: "status.yaml",
+      }
+      const content = fileContents(ctx, feature, map[args.section])
+      return content || `${args.section} is empty.`
+    },
+  })
+
+const createChangedFilesTool = (ctx: PluginContext) =>
+  tool({
+    description: "Read the changed files tracked for the active feature.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      const status = loadStatus(ctx, feature)
+      return status.changed_files.length ? status.changed_files.join("\n") : "No changed files recorded yet."
+    },
+  })
+
+const createAcceptanceCriteriaTool = (ctx: PluginContext) =>
+  tool({
+    description: "Read only the acceptance criteria from the active feature spec.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      return specAcceptanceCriteria(ctx, feature)
+    },
+  })
+
+const createReviewPacketTool = (ctx: PluginContext) =>
+  tool({
+    description: "Read a review-focused packet with scope, risks, acceptance criteria, and changed files.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      return reviewPacket(ctx, feature)
+    },
+  })
+
+const createRepoDeltaTool = (ctx: PluginContext) =>
+  tool({
+    description: "Compare the live artifact file lists against the actual git working tree changes.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      return repoDelta(ctx, feature)
+    },
+  })
+
+const createUpdateTool = (ctx: PluginContext) =>
+  tool({
+    description: "Update the live artifact state, record checkpoints, and keep the latest handoff packet fresh.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+      summary: tool.schema.string().optional().describe("Short live summary."),
+      next_step: tool.schema.string().optional().describe("Next best action."),
+      owner: tool.schema.string().optional().describe("Current owner."),
+      handoff_to: tool.schema.string().optional().describe("Next owner."),
+      stage: tool.schema.enum(["brainstorm", "planning", "implementation", "verification", "review", "done", "blocked"]).optional().describe("Stage transition."),
+      approved_scope: tool.schema.array(tool.schema.string()).optional().describe("Approved scope bullets."),
+      open_questions: tool.schema.array(tool.schema.string()).optional().describe("Open questions."),
+      risks: tool.schema.array(tool.schema.string()).optional().describe("Risks."),
+      blockers: tool.schema.array(tool.schema.string()).optional().describe("Blockers."),
+      files_of_interest: tool.schema.array(tool.schema.string()).optional().describe("Key files for the next agent."),
+      changed_files: tool.schema.array(tool.schema.string()).optional().describe("Files changed in the current stage."),
+      facts: tool.schema.array(tool.schema.string()).optional().describe("Facts to append into notes."),
+      decisions: tool.schema.array(tool.schema.string()).optional().describe("Decisions to append into notes."),
+      links: tool.schema.array(tool.schema.string()).optional().describe("Links to append into notes."),
+    },
+    async execute(args, toolCtx) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      saveCurrentFeature(ctx, feature)
+      const current = loadStatus(ctx, feature)
+      const next: StatusDocument = {
+        ...current,
+        summary: args.summary ?? current.summary,
+        next_step: args.next_step ?? current.next_step,
+        owner: args.owner ?? current.owner,
+        handoff_to: args.handoff_to ?? current.handoff_to,
+        stage: args.stage ?? current.stage,
+        status: args.stage ?? current.status,
+        updated_at: new Date().toISOString(),
+        approved_scope: args.approved_scope ? unique([...current.approved_scope, ...args.approved_scope]) : current.approved_scope,
+        open_questions: args.open_questions ? unique([...current.open_questions, ...args.open_questions]) : current.open_questions,
+        risks: args.risks ? unique([...current.risks, ...args.risks]) : current.risks,
+        blockers: args.blockers ? unique([...current.blockers, ...args.blockers]) : current.blockers,
+        files_of_interest: args.files_of_interest ? unique([...current.files_of_interest, ...args.files_of_interest]) : current.files_of_interest,
+        changed_files: args.changed_files ? unique([...current.changed_files, ...args.changed_files]) : current.changed_files,
+      }
+      saveStatus(ctx, feature, next)
+      updateNotes(ctx, feature, "Facts", args.facts ?? [])
+      updateNotes(ctx, feature, "Decisions", args.decisions ?? [])
+      updateNotes(ctx, feature, "Links", args.links ?? [])
+      refreshHandoff(ctx, feature, next.handoff_to || toolCtx.agent || "feature-lead", next)
+      appendJsonLine(join(featurePath(ctx, feature), "evidence", "checkpoints.jsonl"), {
+        timestamp: new Date().toISOString(),
+        feature,
+        stage: next.stage,
+        owner: next.owner,
+        next_step: next.next_step,
+      })
+      return `Updated ${feature} at stage ${next.stage}. Next: ${next.next_step}`
+    },
+  })
+
+const createArchiveCheckTool = (ctx: PluginContext) =>
+  tool({
+    description: "Check whether the active feature is ready for /archive.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      return archiveReadiness(ctx, feature)
+    },
+  })
+
+const createFinalizeTool = (ctx: PluginContext) =>
+  tool({
+    description: "Finalize the active feature artifact into archive after validation passes.",
+    args: {
+      feature: tool.schema.string().optional().describe("Feature slug. Uses the active feature when omitted."),
+      final_summary: tool.schema.string().describe("Final shipped summary for archive."),
+    },
+    async execute(args) {
+      const feature = slugify(args.feature || resolveCurrentFeature(ctx) || "active-feature")
+      ensureFeatureScaffold(ctx, feature)
+      const source = featurePath(ctx, feature)
+      const readiness = archiveReadiness(ctx, feature)
+      if (!String(readiness).startsWith("READY")) return readiness
+
+      ensureDir(archiveRoot(ctx))
+      const target = archiveSummaryPath(ctx, feature)
+      writeText(target, archiveSummary(ctx, feature, args.final_summary))
+      appendJsonLine(join(source, "evidence", "checkpoints.jsonl"), {
+        timestamp: new Date().toISOString(),
+        feature,
+        stage: "done",
+        archived: true,
+      })
+      return `Archived ${feature} to ${target}`
+    },
+  })
+
+const createEventHandlers = (ctx: PluginContext) => ({
+  "session.created": async (event: any) => {
+    const feature = resolveCurrentFeature(ctx)
+    if (!feature) return
+    const sessionID = event?.sessionID || event?.session?.id || "unknown"
+    const sessionFile = join(featurePath(ctx, feature), "sessions", `${sessionID}.md`)
+    if (!existsSync(sessionFile)) {
+      writeText(sessionFile, `# Session ${sessionID}\n\n- Feature: ${feature}\n- Started: ${new Date().toISOString()}\n`)
+    }
+  },
+  "command.executed": async (event: any) => {
+    const feature = resolveCurrentFeature(ctx)
+    if (!feature) return
+    appendJsonLine(join(featurePath(ctx, feature), "evidence", "commands.jsonl"), {
+      timestamp: new Date().toISOString(),
+      feature,
+      command: event?.command ?? event?.name ?? "unknown",
+    })
+  },
+  "session.idle": async (event: any) => {
+    const feature = resolveCurrentFeature(ctx)
+    if (!feature) return
+    const sessionID = event?.sessionID || event?.session?.id || "unknown"
+    const sessionFile = join(featurePath(ctx, feature), "sessions", `${sessionID}.md`)
+    const current = readText(sessionFile)
+    writeText(sessionFile, `${current.trimEnd()}\n- Idle at: ${new Date().toISOString()}\n`)
+  },
+})
+
+const createToolHooks = (ctx: PluginContext) => ({
+  before: async (input: any) => {
+    const feature = resolveCurrentFeature(ctx)
+    if (!feature) return
+    appendJsonLine(join(featurePath(ctx, feature), "evidence", "tools.jsonl"), {
+      timestamp: new Date().toISOString(),
+      phase: "before",
+      tool: input?.tool ?? "unknown",
+    })
+  },
+  after: async (input: any, output: any) => {
+    const feature = resolveCurrentFeature(ctx)
+    if (!feature) return
+    const status = loadStatus(ctx, feature)
+    const args = output?.args ?? input?.args ?? {}
+    const changed = typeof args.filePath === "string"
+      ? [args.filePath]
+      : Array.isArray(args.filePaths)
+        ? args.filePaths.filter((value: unknown) => typeof value === "string")
+        : []
+    if (changed.length) {
+      status.changed_files = unique([...status.changed_files, ...changed])
+      status.files_of_interest = unique([...status.files_of_interest, ...changed])
+      status.updated_at = new Date().toISOString()
+      saveStatus(ctx, feature, status)
+      refreshHandoff(ctx, feature, status.handoff_to, status)
+    }
+    appendJsonLine(join(featurePath(ctx, feature), "evidence", "tools.jsonl"), {
+      timestamp: new Date().toISOString(),
+      phase: "after",
+      tool: input?.tool ?? "unknown",
+      changed_files: changed,
+    })
+  },
+})
+
+export default async ({ client, directory }: PluginContext) => {
+  const ctx: PluginContext = { client, directory }
+  const hooks = createToolHooks(ctx)
+
+  return {
+    tool: {
+      session_artifact_acceptance_criteria: createAcceptanceCriteriaTool(ctx),
+      session_artifact_changed_files: createChangedFilesTool(ctx),
+      session_artifact_current: createCurrentTool(ctx),
+      session_artifact_handoff: createHandoffTool(ctx),
+      session_artifact_repo_delta: createRepoDeltaTool(ctx),
+      session_artifact_review_packet: createReviewPacketTool(ctx),
+      session_artifact_section: createSectionTool(ctx),
+      session_artifact_update: createUpdateTool(ctx),
+      session_artifact_archive_check: createArchiveCheckTool(ctx),
+      session_artifact_finalize: createFinalizeTool(ctx),
+    },
+    event: createEventHandlers(ctx),
+    "tool.execute.before": hooks.before,
+    "tool.execute.after": hooks.after,
+  }
+}

package/templates/.opencode/skills/archive-writing/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: archive-writing
+description: Write compact archive summaries that explain what shipped, what changed, what was verified, and what follow-up remains.
+---
+
+# Archive Writing
+
+## Philosophy
+An archive entry should explain the outcome faster than reading the full feature bundle. Preserve signal, not process exhaust.
+
+## Use When
+- A slice of work is approved and worth preserving.
+- A feature is complete enough to summarize for future reference.
+- You need a searchable outcome record instead of a draft bundle.
+
+## Core Moves
+- Lead with what shipped.
+- Name the changed surfaces explicitly.
+- Include the checks that mattered.
+- Leave unresolved follow-up visible.
+- Keep the record short enough to scan in under a minute.
+
+## Recommended Shape
+- What was done
+- Changed files or surfaces
+- Verification signal
+- Risks or follow-up
+
+## Anti-Patterns
+- Replaying the full implementation history.
+- Copying planning docs into archive.
+- Claiming certainty when verification was partial.
+- Hiding open questions.
+
+## Remember
+The archive is for retrieval later, not for proving how hard the work was.

package/templates/.opencode/skills/artifact-discipline/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: artifact-discipline
+description: Keep runtime state in artifacts, retrieve documents through tools, and pass compact intent-only handoffs.
+---
+
+# Artifact Discipline
+
+## Philosophy
+Agents should pass intent, not document dumps. Runtime state belongs in artifacts, and artifacts should be retrieved through tools.
+
+## Use When
+- Work spans more than one stage or more than one subagent.
+- You need durable context through compaction or session breaks.
+- You want deterministic handoff instead of full prompt replay.
+
+## Core Moves
+- Start from `session_artifact_current` or `session_artifact_handoff`.
+- Carry only goal, stage, constraints, and exit criteria in the prompt.
+- Pull spec, notes, and evidence on demand.
+- Write back structured updates instead of freeform memory.
+- Refresh the handoff packet before delegating.
+
+## Anti-Patterns
+- Re-explaining the full feature in every handoff.
+- Treating prompt memory as the source of truth.
+- Updating `status.yaml` manually when an artifact tool can do it.
+- Mixing archived history with active execution state.
+
+## Remember
+If a subagent can resume safely after compaction, the harness is doing its job.