---
name: arc-using
description: Use when an ArcForge task needs routing help or the user asks which ArcForge skill/workflow applies
---

# arc-using

## Purpose

`arc-using` is a bounded router for ArcForge skills. It helps choose the smallest useful workflow for the current task. It is guidance, not a global law.

Use it when:

- The user asks to use ArcForge or an ArcForge skill.
- The task is an ArcForge workflow task: brainstorming, refining specs, planning, implementing epics, verifying, evaluating, or maintaining ArcForge skills.
- You are unsure which ArcForge skill should handle the next step.

Respect higher-priority instructions, explicit user constraints, and the host harness. If a workflow would add more friction than value, do not force it.

## How to Access Skills

**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly. Never use the Read tool on skill files.

**In other environments:** Use the platform's skill-loading mechanism, or read the relevant skill documentation when no tool exists.

## Core Philosophy

- Skills are tools, not laws.
- Prefer the smallest useful workflow.
- File artifacts are the source of truth when the workflow creates them.
- Session context is current workflow state only; resume from files, not memory.
- Strong workflows are opt-in by task fit, not always-on behavior.

## File Artifacts = Truth

SDD pipeline v2 uses per-spec layout:

- `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md` → Design documents
- `specs/<spec-id>/spec.xml` + `specs/<spec-id>/details/*.xml` → Refined specifications
- `specs/<spec-id>/dag.yaml` + `specs/<spec-id>/epics/` → Implementation plans
- Isolated feature work → see Worktree Rule below

## Worktree Rule

ArcForge worktrees live at `~/.arcforge/worktrees/<project>-<hash>-<slug>/`, computed at runtime by `${ARCFORGE_ROOT}/scripts/lib/worktree-paths.js`. Two tiers exist: **epic worktrees** carry an `.arcforge-epic` marker and are coordinator-managed; **generic worktrees** (experiments, hotfixes, review checkouts) carry no marker.

When touching worktrees:

- Don't hardcode paths in output. Use abstract language like "the worktree" or fill paths from CLI output.
- Don't create worktrees manually. For epic work, delegate to `arc-coordinating expand`; for everything else, delegate to `arc-using-worktrees` — so marker schema and DAG sync stay valid.
- Re-entering an **epic** worktree: read its absolute `.path` from `arcforge status --json` (the epic-tier surface); do not reconstruct paths from memory.
- Locating a **generic** worktree: read its `path` from `arcforge worktree list --json` (the generic surface) — never `status --json`, which only knows epic worktrees.
- Direct file-editing belongs in a worktree; base sessions coordinate, worktree sessions implement. The `.arcforge-epic` marker distinguishes an epic worktree from a generic one.

For derivation rules, marker schema, and cleanup semantics, see `docs/guide/worktree-workflow.md`.

## Routing Flow

```dot
digraph skill_flow {
    "User message received" [shape=doublecircle];
    "ArcForge workflow task?" [shape=diamond];
    "Simple/read-only/eval/grading?" [shape=diamond];
    "Choose smallest useful skill" [shape=box];
    "Invoke/read skill" [shape=box];
    "Proceed directly" [shape=box];
    "Act with evidence" [shape=doublecircle];

    "User message received" -> "ArcForge workflow task?";
    "ArcForge workflow task?" -> "Proceed directly" [label="no"];
    "ArcForge workflow task?" -> "Simple/read-only/eval/grading?" [label="yes"];
    "Simple/read-only/eval/grading?" -> "Proceed directly" [label="yes"];
    "Simple/read-only/eval/grading?" -> "Choose smallest useful skill" [label="no"];
    "Choose smallest useful skill" -> "Invoke/read skill";
    "Invoke/read skill" -> "Act with evidence";
    "Proceed directly" -> "Act with evidence";
}
```

## Skill Priority

When multiple skills could apply, choose the smallest useful one:

1. **Clarify intent** — `arc-brainstorming` when requirements or decisions are unclear.
2. **Formalize source of truth** — `arc-refining` when converting a design/decision log into structured specs.
3. **Plan work** — `arc-planning` when a refined spec needs an implementation DAG.
4. **Execute work** — `arc-coordinating`, `arc-dispatching-teammates`, `arc-looping`, or `arc-implementing` based on DAG/worktree context.
5. **Cross-cutting quality** — use discipline skills only when their trigger is actually present.

Examples:

- "Let's build X" → `arc-brainstorming` if design is unclear; `arc-planning` if a refined spec already exists.
- "Fix this bug" → `arc-debugging` if cause is unknown; `arc-tdd` if cause and expected behavior are clear.
- "Implement epic" → `arc-planning` if no `specs/<spec-id>/dag.yaml`; coordination/implementation skills if the DAG exists.
- "Audit this skill/workflow" → `arc-evaluating` when shipping/merge/completion evidence matters.

## Execution & Finishing Choosers

When two skills cover the same step, pick by the concrete condition:

| Decision | Pick |
|----------|------|
| Run a prepared task list | `arc-executing-tasks` (human checkpoints per batch) vs `arc-agent-driven` (fresh subagent per task + two-stage review) |
| Dispatch parallel work | `arc-dispatching-parallel` (independent features, one worktree) vs `arc-dispatching-teammates` (multi-epic via DAG, lead present) |
| Set up an isolated workspace | `arc-coordinating expand` for epic work (DAG-tracked, marker'd); `arc-using-worktrees` for a generic worktree (experiment, hotfix, review checkout — any repo, no DAG) |
| Finish work | `arc-finishing` (Step 0 discriminates on `.arcforge-epic`: epic path = coordinator merge; non-epic path = 4-option gate) |

Full skill catalog: README "What's Inside" or `docs/guide/skills-reference.md`.

## Discipline Skills — Conditional Triggers

These skills activate during a workflow when the condition is present. They are not mandatory pipeline steps for every message.

| Condition | Skill | Gate |
|-----------|-------|------|
| About to write implementation code | `arc-tdd` | Failing test before production code |
| Test fails or unexpected behavior appears | `arc-debugging` | Root cause before fixes |
| About to claim work is complete | `arc-verifying` | Fresh verification evidence before completion claims |
| Task or feature complete | `arc-requesting-review` | Review before proceeding to next task |
| Received code review feedback | `arc-receiving-review` | Technical rigor, not performative agreement |
| User asks about vault health, missing links, or orphan notes | `arc-maintaining-obsidian` audit mode | Propose changes, never auto-modify without approval |
| About to ship, merge, or mark complete a skill, agent, or workflow | `arc-evaluating` | Eval evidence that does not return `INSUFFICIENT_DATA` |

## Instinct & Learning Routes

Five skills touch the diary/instinct system. Route by the concrete trigger, not by the word "remember" — they are distinct entry points, not interchangeable:

| User intent | Skill |
|-------------|-------|
| Capture THIS session's reflections as a diary entry | `arc-journaling` |
| Extract recurring patterns from 5+ accumulated diaries | `arc-reflecting` |
| Manually save ONE insight as an instinct right now | `arc-recalling` |
| Review / confirm / contradict auto-detected instincts | `arc-observing` |
| Review the learning-candidate queue (when optional learning is enabled) | `arc-learning` |

## When Not to Route

Do not force an ArcForge workflow when the task is:

- A simple factual answer or direct clarification.
- Read-only inspection where no workflow decision is needed.
- Harness, eval, or grading execution that must preserve isolation.
- A single-skill eval where `arc-using` would contaminate the behavior under test.
- Explicitly constrained by the user to avoid workflow overhead.
- Outside ArcForge's domain.

In those cases, proceed directly, and only mention ArcForge skills if they materially help.

## User Instructions

User instructions say what outcome matters. ArcForge skills can help decide how to get there, but they do not override user intent, harness constraints, or higher-priority system instructions.
