@rryando/arcs 3.0.0

package/opencode/arcs/skills/deep-pr-review/review-template.md

@@ -0,0 +1,69 @@
+# GitHub Review Body Template
+
+Used as the `body` field of `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews` when posting. Inline comments live in the `comments[]` array; this is the top-level summary.
+
+## Template
+
+```markdown
+## Deep PR Review
+
+**Scope:** <N files, +X/-Y LOC, modules: <list>>
+**Rubric:** <activated dimensions> — others cleared (not applicable)
+**Posting mode:** <1-Critical-only | 2-Critical+actionable | 3-All | 4-Summary>
+
+### Summary
+<1-3 sentences: overall shape of the PR, biggest concern, what's well done>
+
+### Findings
+- 🔴 <count> bug(s)
+- 🟠 <count> risk(s)
+- 🟡 <count> suggestion(s)
+- 🔵 <count> nit(s)
+- ❓ <count> question(s)
+
+<inline comments below this body provide line-level detail>
+
+### Architectural / Performance Handoffs
+<only if any; otherwise omit section>
+- [architecture-review] <reason — e.g. crosses 3 modules, touches god node X>
+- [performance-diagnosis] <reason — e.g. new query in render path>
+
+### Citations Used
+- AGENTS.md §<section> — <what was checked>
+- knowledge/<id> — <what was checked>
+- graphify — <observations, if run>
+
+---
+<!-- arcs:deep-review:meta version=1 commit=<HEAD_SHA> rubric=<activated> mode=<posting-mode> -->
+```
+
+## Field rules
+
+- **Posting mode** field is informational for the author — they see what severity threshold was applied
+- Findings counts are **as posted**, not as found. Mode 1 with 4 nits found shows `🔵 0 nit(s)` — those were dropped
+- Architectural / Performance Handoffs section is omitted entirely if no handoffs (don't show empty headings)
+- The trailing HTML comment is mandatory — used by re-review detection to find prior AI reviews
+
+## Inline comment template (per finding)
+
+```markdown
+<severity-emoji> <severity>: <one-line problem>. <one-line fix>.
+
+<optional 1-2 sentences of why, only if not obvious from problem>
+
+Citation: <AGENTS.md §x | knowledge/<id> | graphify | principle: <name>>
+
+​```suggestion
+<replacement code — only for small line replacements>
+​```
+
+<!-- arcs:deep-review:<finding-id> -->
+```
+
+## Approve-with-comments override
+
+If the user explicitly says "approve" / "lgtm" / "post approve":
+- Set `event: "APPROVE"` on the review API call
+- Top-level body must still list any 🟡 / 🔵 findings as advisory notes
+- Append to body: `**Approved with <N> non-blocking suggestion(s).**`
+- Never auto-elevate to APPROVE without explicit user phrase

package/opencode/arcs/skills/executing-plans/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: executing-plans
+description: Use when you have a written implementation plan to execute in a separate session with review checkpoints
+---
+
+# Skill: executing-plans
+
+## When
+
+You have a written implementation plan to execute task-by-task with verification checkpoints.
+
+**NOT for:**
+- If subagents are available → use `subagent-driven-development` instead (parallel dispatch, two-stage review)
+- If the task needs iterative self-correction without a structured plan → use `loop` instead
+
+> CLI: `arcs --commands --json` for discovery. Mutating commands run directly — no token.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Load plan] --> B{Diagram exists?}
+    B -->|Yes| C[arcs diagram ready slug planId]
+    B -->|No| D[Read plan body for task list]
+    C --> E[Extract per-node metadata]
+    D --> E
+    E --> F{Concerns about plan?}
+    F -->|Yes| G[Raise with human — STOP]
+    F -->|No| H[Select next ready task]
+    H --> I[Transition task → in_progress]
+    I --> J[Execute steps exactly]
+    J --> K[Run verification command]
+    K --> L{Passes?}
+    L -->|No| M{Repeated failure?}
+    M -->|Yes| N[STOP — ask for help]
+    M -->|No| J
+    L -->|Yes| O[Transition task → done]
+    O --> P{More ready tasks?}
+    P -->|Yes| H
+    P -->|No| Q{All tasks done?}
+    Q -->|No| R[Re-scan: arcs diagram ready]
+    R --> P
+    Q -->|Yes| S[Use finishing-a-development-branch skill]
+```
+
+## Diagram-First Task Selection
+
+When plan has `.diagram.mmd`:
+1. `arcs diagram ready <slug> <planId>` → executable nodes (deps all `:::done`)
+2. Read per-node `%%` metadata: `node`, `skill`, `scope`, `files`, `acceptance`, `verify`
+3. After each transition, re-scan for newly-unblocked nodes
+4. If metadata incomplete → fall back to plan body for that task
+
+**Transition requires both flags:** `arcs task transition <slug> <taskId> done --diagramNodeId=T001 --planId=<planId>`
+
+## Sub-Agent Context
+
+Include in sub-agent prompts:
+```bash
+arcs context <slug> --audience=implementer --lean --json
+arcs search <slug> "<task-keywords>" --lean --json
+```
+
+Sub-agents MUST NOT edit `.mmd` files — orchestrator owns diagram updates.
+
+## Review Checkpoint Criteria
+
+**STOP executing immediately when:**
+- Missing dependency or unclear instruction
+- Verification fails repeatedly (2+ attempts)
+- Plan has critical gaps preventing progress
+- Fundamental approach needs rethinking
+
+Ask for clarification rather than guessing. Don't force through blockers.
+
+## Auto-Sync Triggers
+
+Post-execution DAG sync fires automatically when:
+- 3+ tasks transitioned this session
+- New knowledge entries created from discoveries
+- `lastSyncedAt` > 7 days ago
+- Plan reached `done` status
+
+## Constraints
+
+- Review plan critically before starting — raise concerns first
+- Follow plan steps exactly — don't improvise
+- Never skip verifications
+- Never start on main/master without explicit consent
+- Reference sub-skills when plan specifies them
+- Use `finishing-a-development-branch` after all tasks complete

package/opencode/arcs/skills/init-project/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: init-project
+description: Use when initializing a new ARCS project — bootstrapping a repo into the DAG with metadata, docs, and structural knowledge entries. Covers gather → present summary → init → graphify ingestion → fan-out analysis across typed sub-agents.
+---
+
+# Skill: init-project
+
+## When
+
+User wants to track a new project, bootstrap documentation, or connect a repo to the ARCS DAG. Triggers: "new project", "track this repo", "add project X", "init <repo>".
+
+> **Canonical orchestrator workflow:** `src/cli/arcs-orchestrate.ts` under `### INIT Workflow` — this skill mirrors that flow with full operational detail. If the two diverge, the orchestrator prompt wins.
+
+## Flow
+
+```mermaid
+flowchart TD
+    classDef sub fill:#8b5cf6,color:#fff
+
+    A[Gather: name, description, repoUrl?, dependsOn?] --> B[arcs project list → conflict check]
+    B --> C[Present summary to user]
+    C -->|user confirms| D[arcs project init]
+    D --> E[arcs project update-doc × 4]
+    E --> F{graphify on PATH?}
+    F -->|yes| G[graphify update --force --no-cluster]
+    F -->|no| H[Skip graph step, log gap]
+    G --> G2[ingestGraph → ≤20 proposals]
+    G2 --> G3[graphify query / explain for enrichment]:::sub
+    H & G3 --> I[Fan out: system-architect + docs-researcher + tech-architect]:::sub
+    I --> J[Collect proposals → dedup → arcs knowledge create × N]
+    J --> K[Done]
+```
+
+## CLI Primer
+
+```bash
+arcs project init "Foo" --description="..." --path="$(pwd)" --json
+```
+Discovery: `arcs --commands --json`. Mutating commands run directly — no token.
+
+## Constraints
+
+- Do NOT read repo to infer name/description — gather from user
+- Verify `dependsOn` targets exist via `arcs project list --json`
+- `arcs project init` creates empty `plans/`, `knowledge/`, `tasks/` indexes — don't pre-populate
+- Repo analysis is **fan-out across typed agents**, never a generic "analysis sub-agent" (see Agent Dispatch below)
+- Never block INIT on graphify — it's optional. Skip cleanly if missing.
+
+## Graphify Sub-Flow (DEFAULT: ON when binary present)
+
+The orchestrator runs graphify directly during INIT to seed knowledge entries with structural evidence before any sub-agent reads code. This is the default path when `graphify` is on PATH; skip cleanly otherwise.
+
+1. **Detect:** call `detectGraphify()` from `src/utils/graphify.ts`. If unavailable, log "graphify not on PATH; proceeding without graph signal" and skip steps 3–5.
+2. **Trust the gitignore guarantee:** `runExtraction()` already auto-appends `graphify-out/` to `.gitignore` via `ensureGitignoreEntry`. Do NOT redundantly check or modify `.gitignore` from agents — running extraction is sufficient.
+3. **Extract** (AST-only, no LLM API key required):
+   ```bash
+   graphify update <workspacePath> --force --no-cluster
+   ```
+   Produces `<workspacePath>/graphify-out/graph.json`.
+4. **Ingest:** call internal `ingestGraph(graphJsonPath, slug)` → up to 20 `KnowledgeProposal` records (test files filtered):
+   - 8 god nodes (`kind=module`, top 5% degree)
+   - 8 architecture clusters (`kind=architecture`, by community or directory grouping)
+   - 5 cross-module couplings (`kind=gotcha`, high-degree links across top-level dirs)
+5. **Enrich** with read-only graph queries (sub-agents may run these):
+   - `graphify query "entry points and main commands" --graph graphify-out/graph.json --budget 2000` → seeds for "key files" reference entries
+   - `graphify query "core data flow" --graph graphify-out/graph.json --budget 2000` → seeds for "core modules" entries
+   - `graphify explain "<godNodeLabel>" --graph graphify-out/graph.json` → plain-language summary for module entry bodies
+   - `graphify affected "<critical-symbol>" --graph graphify-out/graph.json --depth 2` → reverse-impact map for high-risk modules
+   - `graphify path "<A>" "<B>" --graph graphify-out/graph.json` → shortest dependency path for architecture entries
+6. **Hand to typed agents:** the proposals + query results go to the sub-agents listed in **Agent Dispatch** below; they merge graph evidence with code reading and return finalized knowledge entries.
+7. **Write** the entries directly: `arcs batch --file=ops.json` for one batched invocation, or repeated `arcs knowledge create` per entry.
+
+## Content Guidelines
+
+| Doc | Format |
+|-----|--------|
+| `overview.md` | 2-3 sentence summary + goals |
+| `tasks.md` | `[ ]` backlog / `[/]` in-progress / `[x]` done |
+| `dependencies.md` | Upstream + downstream sections |
+| `knowledge.md` | High-level context + pointers to structured entries |
+
+Update via `arcs project update-doc <slug> <doc> --content="..."`.
+
+## Agent Dispatch (named typed agents — DO NOT default to a generic analysis agent)
+
+| Sub-agent | Owns | Knowledge kinds it produces |
+|-----------|------|----------------------------|
+| `system-architect` | Module boundaries, clusters, dependency direction | `architecture`, `module` |
+| `docs-researcher` | Tech stack, third-party libraries, key files, features | `reference`, `feature` |
+| `tech-architect` | Cross-module couplings, structural gotchas, lessons | `gotcha`, `lesson` |
+| `qa-analyst` (optional) | Coding-style + convention scan from existing code | `pattern` |
+
+Dispatch in parallel — load `dispatching-parallel-agents`. Each agent receives:
+- The relevant `KnowledgeProposal` records from `ingestGraph` (so they don't rediscover what graphify already found)
+- Targeted graphify queries for evidence (e.g., `graphify explain` output for the modules they own)
+- Explicit scope (which files / which kinds to produce)
+
+Each agent returns finalized proposals: `{title, kind, summary, keywords, sourceFiles, body}`. The orchestrator dedups, then writes the entries directly via `arcs knowledge create` (or `arcs batch`).
+
+## Knowledge Categories for Analysis Sub-Agents
+
+| Category | Kind | What to discover | Primary agent |
+|----------|------|------------------|---------------|
+| tech stack | `architecture` | Languages, frameworks, runtimes, build tools, versions | `docs-researcher` |
+| key files | `reference` | Entry points, config files, main modules, purposes | `docs-researcher` (use `graphify query "entry points"`) |
+| code patterns | `pattern` | Recurring design patterns, abstractions, error handling | `qa-analyst` or `system-architect` |
+| coding style | `pattern` | Formatting, linting, import ordering, file organization | `qa-analyst` |
+| core modules | `module` | Core modules / shared functions — what, where, interconnections | `system-architect` (god nodes from graphify) |
+| external services | `module` | APIs, databases, message queues the project interacts with | `docs-researcher` |
+| third-party libraries | `reference` | Key dependencies and why they are used | `docs-researcher` |
+| features | `feature` | Major user-facing or system-facing features | `docs-researcher` |
+| cross-module couplings | `gotcha` | Hot edges between modules surfaced by graphify | `tech-architect` (auto from `ingestGraph`) |
+| architecture clusters | `architecture` | Community / directory groupings from graphify | `system-architect` (auto from `ingestGraph`) |
+
+## Worked Example
+
+```bash
+# 1. Conflict check
+arcs project list --json
+
+# 2. Present summary to user; on confirmation, init
+arcs project init "Foo" --description="Foo CLI tool" --path="$(pwd)" --json
+
+# 3. Update docs
+arcs project update-doc foo overview --content="..." --json
+# ... repeat for tasks, dependencies, knowledge
+
+# 4. Graphify (if available)
+graphify update . --force --no-cluster
+# ingestGraph produces proposals; enrich with graphify query/explain
+
+# 5. Fan out typed agents (parallel)
+#    system-architect → architecture/module entries
+#    docs-researcher  → reference/feature entries
+#    tech-architect   → gotcha/lesson entries
+
+# 6. Write knowledge entries directly
+arcs knowledge create foo "Tech stack: TypeScript + Node 20" --kind=architecture --summary="..." --body="..." --json
+# ... repeat per entry, or use arcs batch
+```
+
+## Exit Conditions
+
+| Condition | Action |
+|-----------|--------|
+| Project already in DAG (slug collision) | Stop. Surface conflict; ask user to rename or use existing |
+| User declines summary | Stop. No mutations performed |
+| `graphify` missing | Continue without graph signal; sub-agents run with code reading only |
+| `dependsOn` target missing | Stop. Ask user to init dependencies first or remove the link |
+| Init succeeds but knowledge fan-out fails | Project exists in DAG; rerun knowledge phase later via SYNC |

package/opencode/arcs/skills/quick-dev/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: quick-dev
+description: Use when the task is fully bounded with no open decisions — rename, refactor, extract, multi-var/multi-file change, API shape already known, config nudge, copy update, trivial targeted bugfix
+---
+
+# Skill: quick-dev
+
+## When
+
+Task is fully bounded — no open decisions, success criteria derivable without asking.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Orient: arcs brief --lean --json] --> K[Knowledge: arcs knowledge search slug keywords]
+    K --> B{Fully bounded?}
+    B -->|Yes| C[Execute change directly]
+    B -->|No| D[Escalate to code-agent or brainstorming]
+    C --> E[Verify: typecheck + lint + affected tests]
+    E --> F[Done — commit only when asked]
+```
+
+## Phase 0: Knowledge Check
+
+```bash
+arcs knowledge search <slug> "<keywords>" --lean --json
+```
+
+Check for patterns, gotchas, and lessons before implementing. Skip only if the change is purely mechanical (rename, config nudge).
+
+## Behaviour
+
+1. Orient with ARCS context + search if pattern-related
+2. Execute directly — no planning doc, no brainstorming, no TDD ritual
+3. Run focused verification (not full suite unless pervasive)
+
+## Escalation
+
+If hidden complexity surfaces mid-task — **pause immediately**, state the issue, offer to switch to `code-agent` or `brainstorming`. Do not silently expand scope.
+
+If self-confidence drops below 80% per `confidence-gate` (open decision, unverified assumption, sibling pattern unclear), escalate to `code-agent` — `quick-dev` does not permit exploration loops; `code-agent` does.
+
+## NOT for
+
+- Tasks with open design decisions → `code-agent`
+- New behaviour or UX changes → `brainstorming`

package/opencode/arcs/skills/requesting-code-review/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: requesting-code-review
+description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements
+---
+
+# Skill: requesting-code-review
+
+## When
+
+After completing a task, major feature, or before merge. Dispatch `arcs:code-reviewer` subagent.
+
+## Flow
+
+```mermaid
+flowchart TD
+    A[Work complete] --> B[Get BASE_SHA and HEAD_SHA]
+    B --> C[Gather project conventions]
+    C --> D[Fill code-reviewer.md template]
+    D --> E[Dispatch arcs:code-reviewer subagent]
+    E --> F{Review results}
+    F -->|Critical| G[Fix immediately]
+    F -->|Important| H[Fix before proceeding]
+    F -->|Minor| I[Note for later]
+    G --> E
+    H --> E
+```
+
+## Template Placeholders
+
+- `{WHAT_WAS_IMPLEMENTED}` — what you built
+- `{PLAN_OR_REQUIREMENTS}` — what it should do
+- `{BASE_SHA}` / `{HEAD_SHA}` — commit range
+- `{PROJECT_CONVENTIONS}` — CLAUDE.md / linter configs / style guides
+
+## When to Request
+
+**Mandatory:** after each subagent task, after major features, before merge to main.
+**Optional:** when stuck, before refactoring, after complex bugfix.
+
+## Red Flags
+
+- Never skip because "it's simple"
+- Never ignore Critical issues
+- Never proceed with unfixed Important issues
+- Always include project conventions in reviewer context
+
+See template at: `requesting-code-review/code-reviewer.md`

package/opencode/arcs/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,179 @@
+# Code Review Agent
+
+You are reviewing code changes for production readiness. Write your findings like a thoughtful teammate, not a linter.
+
+**Your task:**
+1. Read the project conventions below **before judging anything**
+2. Review {WHAT_WAS_IMPLEMENTED}
+3. Compare against {PLAN_OR_REQUIREMENTS}
+4. Check code quality, architecture, testing
+5. Categorize issues by severity with inline diff anchors
+6. Assess production readiness
+
+## Project Conventions
+
+{PROJECT_CONVENTIONS}
+
+**Rule:** Never flag something as wrong if it matches the project's own established patterns.
+
+## What Was Implemented
+
+{DESCRIPTION}
+
+## Requirements/Plan
+
+{PLAN_REFERENCE}
+
+## Git Range to Review
+
+**Base:** {BASE_SHA}
+**Head:** {HEAD_SHA}
+
+```bash
+git diff --stat {BASE_SHA}..{HEAD_SHA}
+git diff {BASE_SHA}..{HEAD_SHA}
+```
+
+## Review Checklist
+
+**Project Conventions (check first):**
+- Does the code follow naming, structure, and style patterns already established in this repo?
+- Any deviation from the patterns documented in {PROJECT_CONVENTIONS}?
+
+**Code Quality:**
+- Clean separation of concerns?
+- Proper error handling?
+- Type safety (if applicable)?
+- DRY principle followed?
+- Edge cases handled?
+
+**Architecture:**
+- Sound design decisions?
+- Scalability considerations?
+- Performance implications?
+- Security concerns?
+
+**Testing:**
+- Tests actually test logic (not mocks)?
+- Edge cases covered?
+- Integration tests where needed?
+- All tests passing?
+
+**Requirements:**
+- All plan requirements met?
+- Implementation matches spec?
+- No scope creep?
+- Breaking changes documented?
+
+**Production Readiness:**
+- Migration strategy (if schema changes)?
+- Backward compatibility considered?
+- Documentation complete?
+- No obvious bugs?
+
+## Output Format
+
+### Strengths
+[What's well done? Be specific. Sound like a colleague giving genuine praise, not a form response.]
+
+### Issues
+
+All issues must include a **file:line anchor** pointing to the specific diff line. Write in a collegial tone — direct but not harsh.
+
+#### Critical (Must Fix)
+[Bugs, security issues, data loss risks, broken functionality]
+
+#### Important (Should Fix)
+[Architecture problems, missing features, poor error handling, test gaps]
+
+#### Minor (Nice to Have)
+[Code style, optimization opportunities, documentation improvements]
+
+**For each issue:**
+```
+📍 path/to/file.ts:42
+  Change: [what changed — show old → new if helpful]
+  Finding: [what looks off]
+  Why it matters: [practical impact]
+  Suggested direction: [concrete fix or question]
+```
+
+**Tone guide:**
+- "Heads up — this can throw if X is null (line 42), since you removed the guard"
+- "Worth double-checking: the fallback here (line 88) looks unreachable given the condition above"
+- "Minor nit: this magic number (line 130) could be a named constant for readability"
+
+Not:
+- "VIOLATION: null check missing"
+- "This is wrong"
+
+### Recommendations
+[Improvements for code quality, architecture, or process — written as suggestions, not mandates]
+
+### Assessment
+
+**Ready to merge?** [Yes/No/With fixes]
+
+**Reasoning:** [Technical assessment in 1-2 sentences]
+
+## Critical Rules
+
+**DO:**
+- Read project conventions before evaluating style or patterns
+- Categorize by actual severity (not everything is Critical)
+- Be specific with file:line anchors
+- Explain WHY issues matter
+- Acknowledge strengths
+- Give clear verdict
+- Sound like a teammate, not a linter
+
+**DON'T:**
+- Flag something as wrong if it matches the project's own conventions
+- Say "looks good" without checking
+- Mark nitpicks as Critical
+- Give feedback on code you didn't review
+- Be vague ("improve error handling")
+- Avoid giving a clear verdict
+- Use harsh or robotic phrasing
+
+## Example Output
+
+```
+### Strengths
+- Clean database schema with proper migrations (db.ts:15-42) — easy to follow
+- Comprehensive test coverage (18 tests, all edge cases hit)
+- Good error handling with fallbacks (summarizer.ts:85-92)
+
+### Issues
+
+#### Important
+
+1. 📍 index-conversations:1-31
+   Change: Added CLI wrapper without help flag
+   Finding: No --help flag; users won't discover --concurrency
+   Why it matters: Discoverability — first-time users will hit a wall
+   Suggested direction: Add `--help` case with a short usage example
+
+2. 📍 search.ts:25-27
+   Change: Added date filtering without validation
+   Finding: Invalid dates silently return no results instead of erroring
+   Why it matters: Silent failures are hard to debug
+   Suggested direction: Validate ISO format and throw with an example date
+
+#### Minor
+
+1. 📍 indexer.ts:130
+   Change: Added batch loop with no progress output
+   Finding: Long operations give no feedback
+   Suggested direction: A simple "X of Y" counter would help
+
+### Recommendations
+- Consider a config file for excluded projects — hardcoded list will grow
+- Progress reporting would meaningfully improve UX for large repos
+
+### Assessment
+
+**Ready to merge: With fixes**
+
+**Reasoning:** Core implementation is solid with good architecture and tests. The Important issues (help text, date validation) are quick fixes and don't affect core functionality.
+```