@bfirestone45/opencode-arc 0.3.1

package/skills/arc-implement/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: arc-implement
+description: Use when executing planned arc implementation tasks in OpenCode, especially when the user says to implement a task, continue coding, or run the subagent workflow. Use this instead of direct coding when work should flow through arc-implementer, arc-reviewer, arc-evaluator, or arc-doc-writer.
+---
+
+# Arc Implement
+
+Run arc implementation as explicit orchestrator work. The main agent manages task state, dispatches named OpenCode subagents, and decides whether another pass is required. The main agent does not write the task implementation directly.
+
+## Core Rule
+
+**Orchestrate first, dispatch second, edit code never.** If work needs to be built, reviewed, or accepted, start a named OpenCode subagent task for the correct agent, pass the task/design/test context in that dispatch, and wait for a structured result before continuing.
+
+This skill starts from tracked work that already exists. Use `arc ready` and `arc show <task-id>` to select work; do not create issues or infer ad hoc work that bypassed `arc-plan`.
+
+## Default Mode
+
+Use a sequential workflow unless the user explicitly asks for something else and the runtime clearly supports it. Do not rely on worktree isolation, `isolation: "worktree"`, or Codex-only tool names.
+
+## Orchestration Loop
+
+### 1. Create or Update the Todo List
+
+Before dispatching anything, create or refresh a short todo list for the current task batch. Keep one entry per arc task and update it as work moves through implementation, review, and acceptance.
+
+Minimum statuses:
+- `pending` before dispatch
+- `in_progress` while a subagent is working
+- `needs_fix` when findings require another pass
+- `done` after review and acceptance are clear
+
+### 2. Find and Claim the Task
+
+Use arc to identify the next unblocked task and claim it:
+
+```bash
+arc ready
+arc update <task-id> --take
+arc show <task-id>
+```
+
+Record the current commit before dispatching so later review has a stable base:
+
+```bash
+PRE_TASK_SHA=$(git rev-parse HEAD)
+```
+
+### 3. Check for `docs-only`
+
+If the task is documentation-only, do not send it through the full code path.
+
+```bash
+arc show <task-id> --json | jq -e '.labels[] | select(. == "docs-only")' > /dev/null 2>&1
+```
+
+If the label is present, dispatch `arc-doc-writer` with the task description and skip the evaluator path. Use `arc-reviewer` only when the docs change is substantial enough to benefit from a second pass, such as broad restructuring or operator-facing behavior changes. Do not dispatch `arc-implementer` for docs-only work.
+
+Dispatch prompt shape:
+
+```text
+Write or update the documentation described below.
+
+## Task
+<paste output of: arc show <task-id>>
+
+Stay within the listed files, verify formatting quality, and report back with files changed and checks performed.
+```
+
+OpenCode dispatch shape:
+
+```text
+Start a named subagent/task using agent `arc-doc-writer`.
+Pass the full prompt above plus the pasted `arc show <task-id>` output.
+Expect back: `PASS`, `PARTIAL`, or `NEEDS_CONTEXT`, followed by files changed and checks performed.
+```
+
+### 4. Dispatch `arc-implementer`
+
+For non-docs work, dispatch `arc-implementer` with the full task spec and project test command.
+
+Dispatch prompt shape:
+
+```text
+Implement this task using TDD.
+
+## Task
+<paste output of: arc show <task-id>>
+
+## Context
+Parent issue, completed prerequisites, and any already-landed shared types or files.
+
+## Project Test Command
+<project test command>
+
+## Scope Rules
+- Build only what the task specifies.
+- Stay inside the task's scoped files.
+- If a prerequisite is missing or the task is ambiguous, report `NEEDS_CONTEXT`.
+- If non-blocking issues are noticed outside scope, report `DONE_WITH_CONCERNS`.
+
+Commit only after your gate passes.
+```
+
+OpenCode dispatch shape:
+
+```text
+Start a named subagent/task using agent `arc-implementer`.
+Pass the full prompt above, including the pasted task output, context, and project test command.
+Expect back: `PASS`, `PARTIAL`, `NEEDS_CONTEXT`, or `DONE_WITH_CONCERNS`, plus a short implementation summary, files changed, tests run, and whether the work was committed.
+```
+
+### 5. Triage the Implementation Result
+
+Read the subagent report before doing anything else.
+
+If the result is `PASS`:
+- Run the project test command yourself.
+- If that passes, continue to review and acceptance.
+
+If the result is `PARTIAL` or `NEEDS_CONTEXT`:
+- Read the unresolved or missing-context section closely.
+- Fix missing prerequisites or clarify the task before dispatching again.
+- Re-dispatch `arc-implementer` only with the specific gaps called out.
+
+If the result is `DONE_WITH_CONCERNS`:
+- Preserve the concern in task notes.
+- Continue if the in-scope work is complete and verified.
+
+If the gate was skipped or the report is incomplete:
+- Treat it as a failed pass.
+- Re-dispatch `arc-implementer` with an explicit instruction to complete the full gate.
+
+### 6. Dispatch `arc-reviewer`
+
+After a successful implementation pass, dispatch `arc-reviewer` on the resulting work.
+
+Compute the review input first. Use the committed range when the implementer created one or more commits; otherwise diff the working tree against the pre-task base so the review is not empty.
+
+```bash
+BASE_SHA=$PRE_TASK_SHA
+HEAD_SHA=$(git rev-parse HEAD)
+if [ "$HEAD_SHA" != "$BASE_SHA" ]; then
+  git diff $BASE_SHA..$HEAD_SHA
+else
+  git diff $BASE_SHA
+fi
+```
+
+If the uncommitted implementation added new files, include those paths from `git status --short` in the review context so the reviewer sees the full task output.
+
+Dispatch prompt shape:
+
+```text
+Review these changes for bugs, regressions, missing verification, and plan drift.
+
+## Task Spec
+<paste output of: arc show <task-id>>
+
+## Design Spec
+<paste relevant design excerpt if available>
+
+## Changes
+<paste output of the diff selected by the rule above>
+
+Report findings first with file references. Keep any summary brief and secondary.
+```
+
+OpenCode dispatch shape:
+
+```text
+Start a named subagent/task using agent `arc-reviewer`.
+Pass the task spec, any relevant design excerpt, and the diff produced by the rule above.
+Expect back: findings grouped by severity with file references, then a brief summary.
+```
+
+### 7. Dispatch `arc-evaluator`
+
+After review is dispatched, dispatch `arc-evaluator` for acceptance. Keep this sequential by default in OpenCode: reviewer first or evaluator first is fine, but do not require simultaneous worktree-based execution.
+
+Dispatch prompt shape:
+
+```text
+Evaluate whether this implementation satisfies the task spec from the outside.
+
+## Task Spec
+<paste output of: arc show <task-id>>
+
+## Design Spec
+<paste relevant design excerpt if available>
+
+## Base SHA
+<BASE_SHA>
+
+## Project Test Command
+<project test command>
+```
+
+For docs-only tasks, skip this step and rely on the documentation result plus optional review.
+
+OpenCode dispatch shape:
+
+```text
+Start a named subagent/task using agent `arc-evaluator`.
+Pass the task spec, any relevant design excerpt, the base SHA, and the project test command.
+Expect back: `PASS`, `CONCERNS`, `FAIL`, or `BLOCKED`, with concise acceptance evidence.
+```
+
+### 8. Triage Findings and Decide Whether to Repeat
+
+Another pass happens only when findings require it.
+
+Re-dispatch `arc-implementer` when:
+- `arc-reviewer` reports Critical or Important issues
+- `arc-reviewer` identifies a design deviation that should be fixed
+- `arc-evaluator` reports `FAIL`
+- `arc-evaluator` reports `CONCERNS` that the orchestrator decides must be fixed now
+
+Do not re-run the whole loop just because a reviewer noted a Minor issue or because the evaluator was `BLOCKED` by its own setup.
+
+When re-dispatching, include:
+- the original task spec
+- the specific reviewer or evaluator finding
+- the exact file references or failed behaviors
+- the same project test command
+
+After fixes, run review again and run acceptance again.
+
+### 9. Close the Task
+
+Once implementation, review, and acceptance are clear for the current task:
+
+```bash
+arc close <task-id> --reason "Implemented: <short summary>"
+```
+
+Update the todo list entry to `done`, then move to the next ready task.
+
+## Triage Rules
+
+| Source | Result | Action |
+|--------|--------|--------|
+| `arc-reviewer` | Critical / Important | Re-dispatch `arc-implementer`, then re-review |
+| `arc-reviewer` | Minor | Note it, usually proceed |
+| `arc-reviewer` | Deviation with `fix` | Re-dispatch `arc-implementer` |
+| `arc-reviewer` | Deviation with `accept` | Record rationale, then proceed |
+| `arc-evaluator` | `PASS` | Proceed |
+| `arc-evaluator` | `CONCERNS` | Decide whether to fix now or defer |
+| `arc-evaluator` | `FAIL` | Re-dispatch `arc-implementer`, then re-evaluate |
+| `arc-evaluator` | `BLOCKED` | Do not blame the implementer automatically; note the inconclusive acceptance result |
+
+## Circuit Breaker
+
+If the same finding survives three fix cycles, stop and escalate with:
+- the task ID
+- the repeated finding
+- the competing interpretations of the spec
+- what evidence each agent produced
+
+## Rules
+
+- Keep the workflow sequential by default.
+- Start only from tracked work surfaced by `arc ready`.
+- Do not rely on `isolation: "worktree"`.
+- Do not use Codex-only task tools or workflow names.
+- Do not create issues or infer ad hoc work that bypassed `arc-plan`.
+- Use `arc-doc-writer` instead of the full code path for docs-only work; review is optional for substantial docs changes and evaluator is skipped.
+- Dispatch `arc-implementer`, then `arc-reviewer`, then `arc-evaluator` in substance for code tasks.
+- Repeat only when findings require another pass.
+- Format all arc issue content using `skills/arc/_formatting.md`.

package/skills/arc-plan/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: arc-plan
+description: Use when an approved Arc design needs to be converted into truthful tracked work before implementation starts. Prefer this over generic planning when the project uses Arc plans and issue tracking.
+---
+
+# Arc Plan
+
+Turn an approved Arc design into ordered tracked work and hand off to `arc-implement` only after the work exists.
+
+<HARD-GATE>
+Do NOT implement, scaffold implementation files, or bypass tracked work creation while planning. This skill owns issue creation and ends before implementation starts.
+</HARD-GATE>
+
+## Ordered Checklist
+
+Follow these items in order.
+
+1. **Read the approved design**
+   - Run `arc plan show <plan-id>`.
+   - Read the approved design, plan status, and file path from the planner output before creating tasks.
+   - Verify that the plan status is approved before proceeding.
+   - If the plan is deferred, pending review, or otherwise not approved, stop and direct the user back to planner review instead of creating tracked work.
+2. **Restate the approved goal and constraints**
+   - Restate the approved goal, scope boundaries, major risks, and non-goals in plain language.
+   - Preserve any shared contracts, foundation work, or dependency ordering established during `arc-brainstorm`.
+   - Ask one clarifying question only if something material is still ambiguous.
+3. **Break the design into ordered tasks**
+   - Create a truthful, bounded task list from the approved design.
+   - Keep tasks dependency-ordered.
+   - Use exact file ownership when it is honestly knowable.
+   - If exact files are not yet knowable, name the owning subsystem, contract boundary, or surface instead of pretending certainty.
+   - If shared contracts or setup must land first, create an explicit foundation task and order downstream work behind it.
+4. **Keep the task list realistic**
+   - Do not invent placeholder work, vague cleanup tasks, or hidden phases.
+   - Do not expand scope beyond the approved design.
+   - Keep the breakdown small enough that each item represents a real unit of tracked work.
+5. **Create tracked work through `arc-issue-tracker`**
+   - Use `arc-issue-tracker` to create the tracked work.
+   - Do not create ad hoc issues in `arc-brainstorm` or `arc-implement`.
+   - Create either a single tracked issue for small work or an epic plus child issues for multi-task work.
+   - Preserve dependency ordering and ownership in the tracked work that gets created.
+   - Hand the agent a manifest that includes the approved plan ID, the plan file path from `arc plan show <plan-id>`, the chosen tracked-work shape, the ordered task list, ownership notes, and dependency notes.
+   - Require the agent to return the created Arc IDs, titles, parent-child relationships when applicable, and dependency results so the main session can verify them.
+6. **Confirm tracked work exists**
+   - Verify the issue creation result from `arc-issue-tracker` before moving on.
+   - Check that the returned IDs match the requested tracked-work shape: one issue for the small-work path, or one epic plus the expected child issues for the multi-task path.
+   - Spot-check that parent-child relationships and dependency ordering were created when requested.
+   - Make sure the resulting tracked work matches the approved design and ordered task list.
+7. **Ask for approval before implementation starts**
+    - Present the tracked work summary and execution order.
+    - Ask for approval before handing off to implementation.
+    - If the user changes scope or ordering before approval but the requested changes stay within the approved design, revise the task list and reconcile the already-created tracked work before asking again.
+    - Reconciliation can mean updating issue descriptions, titles, dependencies, or parentage when the existing IDs still fit, or creating replacement tracked work for items that changed materially within the already approved design.
+    - If the requested change materially expands or changes the approved design, stop and send the user back to planner review instead of mutating tracked work in place.
+    - Re-verify the reconciled tracked work after those changes before asking for approval again.
+    - Keep the final approval tied to the actual tracked work that now exists, not the stale pre-change version.
+8. **Hand off only after tracked work exists**
+   - Route to `arc-implement` only after the tracked work has been created.
+   - Do not begin implementation inside this skill.
+
+## Planning Rules
+
+- Start from `arc plan show <plan-id>`.
+- Require `arc plan show <plan-id>` to report an approved plan before creating tracked work.
+- Restate the approved goal and constraints before writing tasks.
+- Preserve shared contracts and dependency ordering from brainstorm.
+- Keep the task list truthful and bounded.
+- Use exact file ownership when honestly knowable.
+- Create tracked work through `arc-issue-tracker`.
+- Support a single issue when the approved design is genuinely small.
+- Make the tracked-work shape explicit: single issue for small work, or epic plus child issues for multi-task work.
+- Do not absorb material design changes after issue creation; route those back to planner review.
+- Ask for approval before implementation starts.
+- Do not implement while planning.
+
+## Tracked Work Standard
+
+The planning output should be Arc-ready tracked work, not a generic outline.
+
+- Create an epic plus child issues when the design spans multiple work items.
+- Create a single tracked issue when the design is small enough that extra issue splitting would be fake precision.
+- Give `arc-issue-tracker` a manifest with the plan reference, task order, ownership, and dependency expectations.
+- Verify the returned Arc IDs, shape, and dependencies before asking for approval.
+- Keep dependencies explicit.
+- Keep ownership explicit.
+- Keep the breakdown aligned to the approved design instead of adding speculative follow-up work.
+
+## Completion Condition
+
+This skill is complete when:
+
+- `arc plan show <plan-id>` has been used to read the approved design,
+- `arc plan show <plan-id>` has confirmed the plan is approved,
+- the approved goal and constraints have been restated,
+- shared contracts and dependency ordering from brainstorm have been preserved,
+- one or more tracked issues have been created through `arc-issue-tracker`,
+- the user has approved the tracked work before implementation, and
+- the handoff goes to `arc-implement` only after tracked work exists.

package/skills/arc-review/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: arc-review
+description: Use when reviewing work that was implemented for an arc task, especially after arc-implement or when the user asks for a code review of task changes. Use this to dispatch arc-reviewer, inspect bugs and regressions, and triage findings before task closure.
+---
+
+# Arc Review
+
+Review task work by dispatching `arc-reviewer`, then triage the result. This skill is for review, not implementation.
+
+## Review Goal
+
+Check the work for:
+- bugs
+- behavioral regressions
+- missing or weak verification
+- plan or spec drift
+
+The review output must put findings first, each with a file reference when possible. Summaries stay brief and secondary.
+
+## Workflow
+
+### 1. Determine the Review Range
+
+Prefer the SHA captured before implementation:
+
+```bash
+BASE_SHA=$PRE_TASK_SHA
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+If implementation work was committed, review `git diff $BASE_SHA..$HEAD_SHA`.
+
+If `HEAD_SHA` is still `BASE_SHA`, the implementer left working-tree edits instead of a commit; review `git diff $BASE_SHA` so tracked staged and unstaged changes are included.
+
+If the uncommitted implementation added new files, include those paths from `git status --short` in the review context so the reviewer does not miss them.
+
+If that value is unavailable, determine the range manually:
+
+```bash
+git log --oneline -10
+BASE_SHA=$(git rev-parse <commit-before-task>)
+HEAD_SHA=$(git rev-parse HEAD)
+```
+
+### 2. Gather the Task and Design Context
+
+Retrieve the task spec:
+
+```bash
+arc show <task-id>
+```
+
+If the task belongs to an epic or has approved design material, retrieve only the relevant design excerpt. The reviewer should compare the implementation against both the task spec and any approved design decisions.
+
+### 3. Dispatch `arc-reviewer`
+
+Dispatch `arc-reviewer` with the task spec, design excerpt if present, and the git diff.
+
+Dispatch prompt shape:
+
+```text
+Review these changes for bugs, regressions, missing verification, and design drift.
+
+## Task Spec
+<paste output of: arc show <task-id>>
+
+## Design Spec
+<paste relevant design excerpt if available>
+
+## Changes
+<paste output of the diff selected by the committed-vs-working-tree rule>
+
+Report findings first with file references. Keep the summary brief and secondary.
+```
+
+OpenCode dispatch shape:
+
+```text
+Start a named subagent/task using agent `arc-reviewer`.
+Pass the full prompt above, including the pasted task spec, any design excerpt, and the diff selected by the committed-vs-working-tree rule.
+Expect back: findings grouped by severity with file references, then a brief summary.
+```
+
+### 4. Evaluate the Review Report
+
+Handle the report in this order:
+
+1. Read all Critical findings.
+2. Read all Important findings.
+3. Read Minor findings.
+4. Read any plan-adherence section.
+5. Read the summary last.
+
+Do not start from the summary. The point of this skill is findings first triage.
+
+### 5. Triage by Severity
+
+| Review result | Action |
+|---------------|--------|
+| Critical | Re-dispatch `arc-implementer` with the exact finding and file references |
+| Important | Re-dispatch `arc-implementer` before task closure |
+| Minor | Note for later or accept explicitly |
+| Deviation with `fix` | Re-dispatch `arc-implementer` to match the approved design |
+| Deviation with `accept` | Record the rationale on the task, then proceed |
+
+When fixes are needed, send the finding back with concrete evidence:
+- the file reference
+- what behavior or verification is missing
+- why it matters
+
+After fixes land, re-run this review workflow on the updated diff.
+
+### 6. Reviewer Discipline
+
+Treat these as the default review questions:
+- Could this change break an existing path?
+- Does the task spec require behavior that is untested or only partially tested?
+- Is the implementation relying on assumptions the spec does not support?
+- Does the code drift from nearby project conventions in a way that increases risk?
+
+### 7. Circuit Breaker
+
+If three review and fix cycles fail to resolve the same finding, stop and escalate with:
+- the repeated finding
+- the file references involved
+- the current implementation response
+- the open question that is blocking agreement
+
+## Output Standard
+
+The effective output shape from `arc-reviewer` should be:
+
+```markdown
+## Critical
+- `path/to/file:line` <problem and why it matters>
+
+## Important
+- `path/to/file:line` <problem and why it matters>
+
+## Minor
+- `path/to/file:line` <problem and why it matters>
+
+## Plan Adherence
+- `ADHERENT` or explicit deviations
+
+## Summary
+<brief secondary wrap-up>
+```
+
+If there are no findings, say so explicitly and keep the summary short.
+
+## Rules
+
+- Review for bugs, regressions, and missing verification before anything else.
+- Keep findings first.
+- Include file references whenever the evidence supports them.
+- Keep summaries brief and secondary.
+- Never make code changes in this skill; send fixes back to `arc-implementer`.
+- Format all arc issue content using `skills/arc/_formatting.md`.

package/skills/arc-verify/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: arc-verify
+description: Use before claiming an arc-tracked task is fixed, complete, or ready to close in OpenCode, especially when success depends on test, build, or command output that must be checked fresh.
+---
+
+# Arc Verify
+
+Verify every completion claim with a fresh proof command and its full output.
+
+## Core Rule
+
+**No success claim without fresh verification evidence.**
+
+## Gate Sequence
+
+### 1. Identify the proof command
+
+- Choose the command that proves the exact claim.
+- Examples:
+  - "tests pass" -> the relevant test command
+  - "build succeeds" -> the project build command
+  - "issue is ready to close" -> the command or output that shows the acceptance condition is met
+- If no command can prove the claim directly, say that and report the real state.
+
+### 2. Run it
+
+- Run the full command now.
+- Prefer the broadest meaningful check over a hand-picked subset.
+- Do not rely on memory, cached output, or another agent's report.
+
+### 3. Read the full output
+
+- Read the complete output, not just the last line.
+- Check the exit status, failures, warnings, skipped work, and anything that weakens the claim.
+- If output is long, inspect it fully before summarizing it.
+
+### 4. Decide what the output proves
+
+- Confirm whether the output supports the exact statement you want to make.
+- Separate partial evidence from complete proof.
+
+### 5. Only then make the claim
+
+- State the result together with the evidence.
+- Example: `npm test` exited 0 and reported 128 passed, 0 failed.
+- If verification failed, report that directly and return to implementation or debugging.
+
+## Red Flags
+
+- "Should pass"
+- "Looks good"
+- Claiming success before running the proof command
+- Reading only a summary line
+- Treating partial output as complete evidence
+
+## Arc Notes
+
+- Close or update arc issues only after verification matches reality.
+- Keep issue comments factual and tied to command output.
+- Format any arc notes per `skills/arc/_formatting.md`.

package/version.txt

@@ -0,0 +1 @@
+0.3.1