@frankzhang2026/opencode-android-orchestrator 0.1.0 → 0.3.0

package/templates/.opencode/skills/scheduled-quality-reviewer/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: scheduled-quality-reviewer
+description: Use when an orchestrated read-only OpenCode reviewer must independently assess one sealed task in REVIEWING and submit a gated decision
+compatibility: opencode
+metadata:
+  audience: automation
+  workflow: scheduled-review
+---
+
+# Scheduled quality reviewer
+
+Review exactly one task from a fresh session. The coder's summary is a claim,
+not evidence. You have no repository write authority and must not fix the code
+you review.
+
+## Mandatory sequence
+
+1. Load `verification-before-completion`.
+2. Require exactly one task ID or the compatibility token
+   `NEXT_REVIEWING`. For the selector token, first run
+   `./scripts/automation/select-task.sh REVIEWING` and continue only if
+   exactly one task ID is returned. Then run
+   `./scripts/automation/status.sh <TASK-ID>`.
+3. Continue only when state is `REVIEWING`; the orchestrator alone performs
+   the sealed handoff from `READY_FOR_REVIEW`.
+4. The `status.sh` JSON already includes the approved contract, baseline
+   metadata, RED evidence, latest gate metadata, current diff SHA, and the
+   sealed-SHA comparison. Use that compact evidence object; do not try to read
+   the external shared evidence directory or search generated Gradle report
+   directories. Inspect the actual tracked product change with exactly
+   `git diff`. The plan and task contract remain uncommitted and are included
+   in the sealing scripts' full task SHA even when plain `git diff` does not
+   render those untracked files; their hashes are protected, and only product
+   paths count against `allowedPaths` and `maxChangedFiles`.
+5. Check each acceptance criterion against observable behavior. Inspect for
+   regression risk, missing edge cases, out-of-scope changes, test deletion,
+   ignored tests, relaxed assertions, and implementation-shaped tests.
+6. Decide independently:
+
+   - approve only when the diff is correct and evidence is sufficient;
+   - request changes for every material finding, with a concrete file/behavior
+     explanation.
+7. Submit one decision as soon as the inspection supports it:
+
+   `./scripts/automation/submit-review.sh <TASK-ID> APPROVED <summary>`
+
+   or
+
+   `./scripts/automation/submit-review.sh <TASK-ID> CHANGES_REQUESTED <summary>`
+
+   The script reruns the focused tests, full unit suite, debug build, and lint
+   before accepting `APPROVED`, and records that fresh output. Therefore do not
+   run those Gradle commands separately before an approval submission. Run an
+   individual verification command only to diagnose a failed submission, and
+   always reserve a step for the final `submit-review.sh` call.
+
+## Independence rules
+
+- Never edit code, tests, contracts, agent definitions, skills, scripts, or
+  evidence produced by the coder.
+- Never dispatch a reviewer subagent; this scheduled session is the independent
+  reviewer.
+- Never approve because the coder says tests passed. The fresh output produced
+  by `submit-review.sh` is the authoritative independent verification.
+- Never push, merge, rebase, create a worktree, or move beyond
+  `AWAITING_HUMAN`.
+- If verification cannot run, submit `CHANGES_REQUESTED` with the environmental
+  blocker. Do not manufacture approval.

package/templates/AGENTS.md.fragment

@@ -0,0 +1,19 @@
+<!-- opencode-android-orchestrator:begin -->
+## OpenCode Android Orchestrator
+
+Run orchestration commands from the Git repository root.
+
+For automated local unit-test verification, run `./gradlew testDebugUnitTest`
+as a standalone command. Do not prepend environment assignments or wrap it in
+another script; this keeps the invocation aligned with the installed OpenCode
+command allowlist.
+
+Treat `.opencode/`, `automation/`, `scripts/automation/`, `opencode.json`,
+and this managed block as orchestration infrastructure. Product tasks must not
+modify them unless an explicitly approved task is scoped to maintaining the
+orchestrator itself.
+
+Only a fresh OpenCode single-choice `question` selection can grant an
+orchestration approval. Approval-like text in ordinary chat is not approval.
+The orchestrator must not push Git changes or register scheduler/launchd jobs.
+<!-- opencode-android-orchestrator:end -->

package/templates/README.md

@@ -1,14 +1,60 @@
 # Installation templates
 
-This directory will contain the project-local OpenCode resources extracted
-from the verified Android orchestration V3 baseline.
+The project-local OpenCode agents, commands, and skills in `.opencode/` derive
+from the verified Android orchestration V3 baseline at source commit
+`829693652e3737ad94c7cc75214b09fb2b58715b`. Project-dependent agent permissions
+are generalized to Android source sets and remain bounded by each task contract.
 
-Planned template roots:
+Migrated template roots:
 
-- `.opencode/agents`, `.opencode/commands`, and `.opencode/skills`
-- `automation` configuration, schemas, and the task contract example
-- `scripts/automation` deterministic shell transactions
-- `docs/plans/README.md`
+- `.opencode/agents`: `scheduled-planner`, `scheduled-coder`, and
+  `scheduled-reviewer`
+- `.opencode/commands`: `change`, `acceptance`, `resume-review`, and
+  `abort-task`
+- `.opencode/skills`: the three `scheduled-quality-*` skills
+- `scripts/automation`: all 28 deterministic V3 Bash transactions and their
+  test runner, preserved as executable files
+- `automation`: the portable V3 configuration render source, both JSON Schemas,
+  and the task contract example
+- `docs/plans/README.md`: the human-approved plan authoring contract
+- `AGENTS.md.fragment`: a bounded managed block for non-destructive
+  merging into an existing project `AGENTS.md`
+- `installation-manifest.schema.json`: the portable JSON Schema for installer
+  control manifests stored at `.automation-plugin/manifest.json`
 
-Historical tasks, runtime evidence, backups, Android product code, and local
-absolute paths must never be included.
+`automation/config.json` is an input to the adaptive renderer, not a directly
+installable configuration. `planAdaptiveProjectTemplates` injects the required
+`androidProject` metadata, repository-relative build files, protected paths,
+all detected production/test source sets, and a module scope. New renders use
+`all` scope and generate task paths for every detected module without requiring
+a primary selection. `primary` scope restricts paths to one module and retains
+the ambiguity guard. The selected/default module still supplies the focused
+test placeholder in both modes.
+
+The legacy Scheduler field has been removed while Superpowers remains pinned.
+The scope gates consume generated source-set arrays, and the Shell test fixture
+uses a neutral custom module and package. No shipped template contains a local
+absolute path or project-specific package name.
+
+`planAgentsConfigMerge` appends this block without replacing existing project
+instructions, preserves LF/CRLF style, is byte-idempotent, and rejects partial,
+duplicate, or modified managed markers. `init` applies the result through the
+same backup and manifest transaction as every other managed file.
+
+Historical tasks, runtime evidence, backups, and Android product code are not
+included.
+
+`tests/template-migration.test.mjs` locks the migrated inventory, current
+SHA-256 values, file modes, and portability constraints.
+
+`tests/shell-template-migration.test.mjs` additionally locks the Shell file
+inventory, current SHA-256 values, `0755` modes, Bash syntax, portability, and
+no-push/no-publish/no-launchd constraints.
+
+`tests/resource-template-migration.test.mjs` locks the five portable
+infrastructure resources, validates their structural alignment, and verifies
+that the AGENTS fragment has exactly one portable managed block.
+
+`tests/install-manifest.test.mjs` validates the package-level installation
+manifest Schema together with backup and recovery metadata generated by the
+installer transaction layer.

package/templates/automation/config.json

@@ -0,0 +1,67 @@
+{
+  "schemaVersion": 3,
+  "enabled": true,
+  "mode": "orchestrated",
+  "workspaceStrategy": "inPlaceExclusive",
+  "originalBranchDriftPolicy": "block",
+  "worktreeBase": "",
+  "maxFixLoops": 1,
+  "maxReviewCycles": 1,
+  "maxReviewerRestarts": 2,
+  "autoCleanupWorktrees": true,
+  "pushAfterAcceptance": false,
+  "approvalPhrases": {
+    "proposal": "批准方案，生成计划和任务合同。",
+    "contract": "合同已复核，批准自动执行到人工验收阶段。",
+    "acceptance": "验收通过，提交到原分支。",
+    "abort": "中止任务，封存修改并恢复原分支。"
+  },
+  "plugins": {
+    "superpowers": "superpowers@git+https://github.com/obra/superpowers.git#v6.2.0"
+  },
+  "requiredSkills": [
+    "brainstorming",
+    "writing-plans",
+    "scheduled-quality-orchestrator",
+    "scheduled-quality-coder",
+    "scheduled-quality-reviewer",
+    "test-driven-development",
+    "systematic-debugging",
+    "verification-before-completion"
+  ],
+  "gradleVerification": {
+    "fullUnitTestTasks": [
+      "testDebugUnitTest"
+    ],
+    "focusedTestTasks": [
+      "testDebugUnitTest"
+    ],
+    "assembleTasks": [
+      "assembleDebug"
+    ],
+    "lintTasks": [
+      "lint"
+    ],
+    "deviceTestTasks": [
+      "connectedDebugAndroidTest"
+    ]
+  },
+  "protectedPaths": [
+    ".opencode/",
+    ".automation-plugin/",
+    "automation/",
+    "scripts/automation/",
+    "opencode.json",
+    "opencode.jsonc",
+    "AGENTS.md",
+    "gradle/",
+    "gradlew",
+    "gradlew.bat",
+    "settings.gradle",
+    "settings.gradle.kts",
+    "build.gradle",
+    "build.gradle.kts",
+    "**/build.gradle",
+    "**/build.gradle.kts"
+  ]
+}

package/templates/automation/config.schema.json

@@ -0,0 +1,194 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frankzhang2026:opencode-android-orchestrator:automation-config:v3",
+  "title": "OpenCode task orchestration configuration",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "repositoryPath": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?!\\.\\.(?:/|$))(?![A-Za-z]:[\\\\/]).+"
+    },
+    "nullableIdentifier": {
+      "type": ["string", "null"],
+      "minLength": 1
+    },
+    "gradleTask": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:[A-Za-z][A-Za-z0-9_.-]*|(?::[A-Za-z0-9_.-]+)+)$"
+    },
+    "gradleTaskList": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/gradleTask" }
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "enabled",
+    "mode",
+    "workspaceStrategy",
+    "originalBranchDriftPolicy",
+    "worktreeBase",
+    "maxFixLoops",
+    "maxReviewCycles",
+    "maxReviewerRestarts",
+    "autoCleanupWorktrees",
+    "pushAfterAcceptance",
+    "approvalPhrases",
+    "plugins",
+    "requiredSkills",
+    "gradleVerification",
+    "androidProject",
+    "protectedPaths"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 3 },
+    "enabled": { "type": "boolean" },
+    "mode": { "enum": ["shadow", "orchestrated"] },
+    "workspaceStrategy": {
+      "enum": ["inPlaceExclusive", "isolatedWorktree"]
+    },
+    "originalBranchDriftPolicy": { "const": "block" },
+    "worktreeBase": { "type": "string" },
+    "maxFixLoops": { "type": "integer", "minimum": 0, "maximum": 1 },
+    "maxReviewCycles": { "type": "integer", "minimum": 0, "maximum": 2 },
+    "maxReviewerRestarts": { "type": "integer", "minimum": 0, "maximum": 3 },
+    "autoCleanupWorktrees": { "type": "boolean" },
+    "pushAfterAcceptance": { "const": false },
+    "approvalPhrases": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["proposal", "contract", "acceptance", "abort"],
+      "properties": {
+        "proposal": { "type": "string", "minLength": 4 },
+        "contract": { "type": "string", "minLength": 4 },
+        "acceptance": { "type": "string", "minLength": 4 },
+        "abort": { "type": "string", "minLength": 4 }
+      }
+    },
+    "plugins": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["superpowers"],
+      "properties": {
+        "superpowers": { "type": "string", "minLength": 1 }
+      }
+    },
+    "requiredSkills": {
+      "type": "array",
+      "minItems": 6,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "gradleVerification": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fullUnitTestTasks",
+        "focusedTestTasks",
+        "assembleTasks",
+        "lintTasks",
+        "deviceTestTasks"
+      ],
+      "properties": {
+        "fullUnitTestTasks": { "$ref": "#/$defs/gradleTaskList" },
+        "focusedTestTasks": { "$ref": "#/$defs/gradleTaskList" },
+        "assembleTasks": { "$ref": "#/$defs/gradleTaskList" },
+        "lintTasks": { "$ref": "#/$defs/gradleTaskList" },
+        "deviceTestTasks": { "$ref": "#/$defs/gradleTaskList" }
+      }
+    },
+    "androidProject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "name",
+        "gradleDsl",
+        "settingsFile",
+        "primaryModule",
+        "modules",
+        "productionPaths",
+        "testPaths"
+      ],
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "gradleDsl": { "enum": ["kotlin", "groovy", "mixed"] },
+        "settingsFile": { "$ref": "#/$defs/repositoryPath" },
+        "moduleScope": { "enum": ["all", "primary"] },
+        "primaryModule": {
+          "type": "string",
+          "pattern": "^:(?:[A-Za-z0-9_.-]+(?::[A-Za-z0-9_.-]+)*)?$"
+        },
+        "modules": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "gradlePath",
+              "directory",
+              "buildFile",
+              "dsl",
+              "type",
+              "namespace",
+              "applicationId"
+            ],
+            "properties": {
+              "gradlePath": {
+                "type": "string",
+                "pattern": "^:(?:[A-Za-z0-9_.-]+(?::[A-Za-z0-9_.-]+)*)?$"
+              },
+              "directory": { "$ref": "#/$defs/repositoryPath" },
+              "buildFile": { "$ref": "#/$defs/repositoryPath" },
+              "dsl": { "enum": ["kotlin", "groovy"] },
+              "type": {
+                "enum": [
+                  "application",
+                  "library",
+                  "dynamic-feature",
+                  "test",
+                  "asset-pack"
+                ]
+              },
+              "namespace": { "$ref": "#/$defs/nullableIdentifier" },
+              "applicationId": { "$ref": "#/$defs/nullableIdentifier" }
+            }
+          }
+        },
+        "productionPaths": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "allOf": [
+              { "$ref": "#/$defs/repositoryPath" },
+              { "pattern": "(^|/)src/main/\\*\\*$" }
+            ]
+          }
+        },
+        "testPaths": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "allOf": [
+              { "$ref": "#/$defs/repositoryPath" },
+              { "pattern": "(^|/)src/(?:test|androidTest)/\\*\\*$" }
+            ]
+          }
+        }
+      }
+    },
+    "protectedPaths": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/repositoryPath" }
+    }
+  }
+}

package/templates/automation/task-contract.schema.json

@@ -0,0 +1,92 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:frankzhang2026:opencode-android-orchestrator:task-contract:v1",
+  "title": "Scheduled coding task contract",
+  "type": "object",
+  "additionalProperties": false,
+  "$defs": {
+    "gradleTask": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:[A-Za-z][A-Za-z0-9_.-]*|(?::[A-Za-z0-9_.-]+)+)$"
+    },
+    "testFilter": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[A-Za-z0-9_.#$*-]+$"
+    }
+  },
+  "required": [
+    "schemaVersion",
+    "id",
+    "title",
+    "designApproved",
+    "planPath",
+    "ambiguityPolicy",
+    "maxFixLoops",
+    "maxChangedFiles",
+    "allowedPaths",
+    "forbiddenPaths",
+    "allowedSuperpowers",
+    "acceptanceCriteria",
+    "nonGoals",
+    "targetTests",
+    "deviceTestsRequired",
+    "testPolicy"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "pattern": "^TASK-[A-Z0-9-]+$" },
+    "title": { "type": "string", "minLength": 1 },
+    "designApproved": { "const": true },
+    "planPath": { "type": "string", "minLength": 1 },
+    "ambiguityPolicy": { "const": "BLOCKED" },
+    "maxFixLoops": { "type": "integer", "minimum": 0, "maximum": 1 },
+    "maxChangedFiles": { "type": "integer", "minimum": 1, "maximum": 12 },
+    "allowedPaths": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "forbiddenPaths": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "allowedSuperpowers": {
+      "type": "array",
+      "const": [
+        "test-driven-development",
+        "systematic-debugging",
+        "verification-before-completion"
+      ]
+    },
+    "acceptanceCriteria": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "nonGoals": {
+      "type": "array",
+      "minItems": 1,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "targetTests": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["gradleTask", "filter"],
+        "properties": {
+          "gradleTask": { "$ref": "#/$defs/gradleTask" },
+          "filter": { "$ref": "#/$defs/testFilter" }
+        }
+      }
+    },
+    "deviceTestsRequired": { "type": "boolean" },
+    "testPolicy": { "enum": ["required", "not-required"] },
+    "testPolicyReason": { "type": "string" }
+  }
+}

package/templates/automation/tasks/TASK-TEMPLATE.json.example

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 1,
+  "id": "TASK-EXAMPLE-001",
+  "title": "Replace with one small, observable behavior change",
+  "designApproved": true,
+  "planPath": "docs/plans/TASK-EXAMPLE-001.md",
+  "ambiguityPolicy": "BLOCKED",
+  "maxFixLoops": 1,
+  "maxChangedFiles": 4,
+  "allowedPaths": [
+    "**/src/main/**",
+    "**/src/test/**",
+    "**/src/androidTest/**"
+  ],
+  "forbiddenPaths": [
+    ".opencode/**",
+    ".automation-plugin/**",
+    "automation/**",
+    "scripts/automation/**",
+    "opencode.json",
+    "opencode.jsonc",
+    "AGENTS.md",
+    "gradle/**",
+    "gradlew",
+    "gradlew.bat",
+    "settings.gradle",
+    "settings.gradle.kts",
+    "build.gradle",
+    "build.gradle.kts",
+    "**/build.gradle",
+    "**/build.gradle.kts"
+  ],
+  "allowedSuperpowers": [
+    "test-driven-development",
+    "systematic-debugging",
+    "verification-before-completion"
+  ],
+  "acceptanceCriteria": [
+    "Replace with an observable input/output or UI behavior",
+    "A focused test demonstrates the behavior and is captured RED before implementation",
+    "Unit tests, debug build, and lint all pass"
+  ],
+  "nonGoals": [
+    "Do not refactor unrelated screens",
+    "Do not upgrade dependencies or Gradle configuration"
+  ],
+  "targetTests": [
+    {
+      "gradleTask": "testDebugUnitTest",
+      "filter": "*ReplaceWithFocusedTest"
+    }
+  ],
+  "deviceTestsRequired": false,
+  "testPolicy": "required",
+  "testPolicyReason": "Behavior changes require a focused regression test"
+}

package/templates/docs/plans/README.md

@@ -0,0 +1,26 @@
+# Human-approved automation plans
+
+Every orchestrated coding contract must reference one plan in this directory.
+Planning is interactive and happens before a task is approved for execution; unattended agents
+must not create, broaden, or reinterpret these plans.
+
+The normal entry point is a natural-language task description entered in an
+interactive `scheduled-planner` OpenCode session. The planner must inspect the
+repository, present the proposed scope and acceptance criteria, and receive
+explicit human approval before it creates this plan and the matching JSON
+contract.
+
+A plan should contain:
+
+- one observable behavior change;
+- acceptance criteria and edge cases;
+- allowed and forbidden repository paths;
+- the focused test class/filter that will provide RED evidence;
+- explicit non-goals;
+- device/emulator requirements, if any;
+- a dated human approval statement.
+
+After proposal approval, Planner seals both artifacts in `CONTRACT_REVIEW`.
+The matching contract belongs in `automation/tasks/TASK-<ID>.json`. A missing
+plan, placeholder text, or mismatched task ID causes contract validation to
+fail.