{
  "id": "page:docs-agent-reference-process-authoring",
  "_kind": "Page",
  "_file": "wiki/docs/agent-reference/process-authoring.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/agent-reference/process-authoring.md",
    "sourceKind": "repo-docs",
    "title": "Process Authoring Policy",
    "displayName": "Process Authoring Policy",
    "slug": "docs/agent-reference/process-authoring",
    "articlePath": "wiki/docs/agent-reference/process-authoring.md",
    "article": "\n# Process Authoring Policy\n\nThese rules are specific to this repository and override more generic process-authoring guidance when they conflict.\n\n## Default Stance\n\n- Always use the Babysitter skill to fulfill user requests in this repo, but not agent-to-agent delegated requests.\n- Keep the orchestration model intact. Do not replace it with helper scripts or ad hoc wrappers.\n- Keep process code aligned with the process-library style and repo conventions.\n\n## Process Shape Selection\n\nChoose the process shape before writing `process.js`:\n\n- Use a flat phase list when the spec is well-defined and the work is wiring or composition. The bug class, if any, is known, and execution should proceed sequentially through clear phases where each phase adds or verifies one defined surface.\n- Use a HYPOTHESES tree when the bug class is unknown and forensics are required. Multiple causal models should compete explicitly, with each hypothesis carrying its own evidence to gather, falsifying observations, and follow-up phases.\n- Rule of thumb: if the first phase is \"investigate\", use HYPOTHESES-tree mode. If the first phase is \"implement X\", use flat-phase-list mode.\n\n## Strike-3 Post-Instrumentation Contract\n\nWhen a Strike-3 or post-instrumentation handoff asks for a data-driven fix,\nthe next source-code fix phase is blocked until the interpretation contract is\nsatisfied:\n\n- Enumerate at least 3 candidate root-cause hypotheses before writing a fix.\n- For each hypothesis, name the falsifying log line or observation that would\n  disprove it.\n- Select the fix only after citing concrete log evidence: use the seq number\n  when present, otherwise cite timestamp, log-id, or artifact path plus the\n  exact log line.\n- If no proposed fix cites at least one specific log line or log record, mark\n  the handoff `needs-more-data` instead of accepting or opening a fix PR.\n\nThis contract is scoped to Strike-3/post-instrumentation fix handoffs. Do not\napply it as a blanket requirement for ordinary first-attempt bug fixes.\n\n## Agent Task Responders\n\nUse internal agent tasks for most contributor-facing process work. They are the\ndefault `kind: \"agent\"` shape and are best for synthesis, review, planning,\nclassification, and other text-first work that does not require a separate agent\nworkspace.\n\n```javascript\nexport const summarizeTask = defineTask(\"summarize-docs\", () => ({\n  kind: \"agent\",\n  title: \"Summarize documentation gaps\",\n  agent: {\n    name: \"docs-gap-summarizer\",\n    prompt: {\n      role: \"technical documentation reviewer\",\n      task: \"Read the target docs and summarize missing contributor guidance.\",\n    },\n  },\n}));\n```\n\nUse an external agent responder only when the work benefits from another\nadapters adapter: for example, tool-heavy code editing, browser or shell access,\na specialist harness, or an isolated conversation context. The current\ntasks-adapter routing model uses `responderType: \"agent\"` plus an `adapter` routing\nhint on the agent task.\n\n```javascript\nexport const implementationReviewTask = defineTask(\"implementation-review\", () => ({\n  kind: \"agent\",\n  title: \"Review implementation with an external responder\",\n  agent: {\n    name: \"external-reviewer\",\n    responderType: \"agent\",\n    adapter: \"codex\",\n    prompt: \"Review the working tree diff and report blocking issues.\",\n    model: \"gpt-5.5\",\n    provider: \"openai\",\n    timeout: 300_000,\n    approvalMode: \"yolo\",\n    maxTurns: 10,\n    fallbackType: \"internal\",\n  },\n}));\n```\n\nExternal agent responders require `adapter`; `model`, `provider`, `timeout`,\n`approvalMode`, and `maxTurns` are optional routing hints passed through to the\nagent responder when the backend supports them. `fallbackType: \"internal\"`\nmeans the task may degrade to the normal internal agent path when adapters or\nthe preferred adapter is unavailable. Without an explicit fallback, a missing\nadapters install, missing adapter, authentication failure, timeout, or adapter\ncrash should surface as a failed task result rather than silently changing\nresponders.\n\nSome design notes and older planning artifacts refer to\n`agent.external: true` and `fallbackToInternal`. Treat those as legacy\nterminology for the same authoring intent; new contributor examples should use\n`responderType: \"agent\"` and `fallbackType: \"internal\"` so tasks-adapter can route\nthe effect consistently.\n\n## `babysitter:call` Override For This Repo\n\nWhen authoring a Babysitter process for a direct user request in this repository:\n\n- Do not generate `kind: 'shell'` subtasks unless the user explicitly asks for a shell-oriented workflow.\n- Prefer `agent` and `skill` tasks for implementation, review, synthesis, and verification steps.\n- Keep breakpoints sparse. Use them only when user input is genuinely critical or the situation is ambiguous.\n- Still include an interview phase up front when requirements or constraints are unclear.\n\nThis is a deliberate repo-specific override of more general guidance that may recommend shell tasks for objective verification.\n\nWhen a shell task returns JSON that later process code reads as structured data, declare a top-level `outputSchema` on the shell `TaskDef`. The shared SDK commit path validates successful posted values before `result.json`, `EFFECT_RESOLVED`, hooks, registry updates, or state-cache mutation. Use `outputSchema: false` or omit the field to preserve unvalidated legacy behavior.\n\n```javascript\nexport const liveVerifyTask = defineTask('live-verify', (args, taskCtx) => ({\n  kind: 'shell',\n  title: 'Live verification',\n  shell: {\n    command: `cd ${args.projectDir || '.'} && node scripts/live-verify.js`,\n    expectedExitCode: 0,\n    timeout: 60000\n  },\n  outputSchema: {\n    type: 'object',\n    required: ['verified', 'checks'],\n    properties: {\n      verified: { type: 'boolean' },\n      checks: { type: 'array' }\n    }\n  },\n  io: {\n    inputJsonPath: `tasks/${taskCtx.effectId}/inputs.json`,\n    outputJsonPath: `tasks/${taskCtx.effectId}/output.json`\n  }\n}));\n```\n\n## `babysitter:plan` Reuse Audit\n\nFor plan-only requests, run Phase 0 -- REUSE-AUDIT before drafting process or\ninfrastructure work:\n\n- Extract keyword nouns and verbs from the user's prompt.\n- Scan for matching migrations, API routes, environment variables, SDK\n  dependencies, and imports.\n- Honor `.a5c/reuse-audit.json` when present for scan globs and keyword\n  extraction rules.\n- Render `Reuse-audit findings (REVIEW BEFORE PROCEEDING)` before Phase 1,\n  including a brief \"No matching existing infrastructure found\" note when the\n  audit has no matches.\n\nThe plan should use these findings as context before proposing new tables,\nroutes, credentials, SDK installs, or equivalent infrastructure.\n\n## Stability Rules\n\n- Do not use the babysit skill inside delegated subtasks.\n- Do not rely on auto-hooks to continue a run in environments where hooks are unavailable; drive the loop explicitly when required.\n- Keep completion criteria explicit and tied to run status, not to optimistic summaries.\n\n## Where To Look Next\n\n- [Runtime And Layout](./runtime-and-layout.md) for replay and run-state behavior\n- [Command Surfaces](./command-surfaces.md) for CLI boundaries\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-agent-reference",
      "to": "page:docs-agent-reference-process-authoring",
      "kind": "contains_page"
    }
  ]
}