| name | arc-using |
| description | Route an ArcForge task to the smallest useful skill or workflow. Use when unsure which skill applies or the user asks where to start — a bounded router and skill index, not an always-on policy engine. |
| category | meta |
| status | promoted |
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. Skills are tools, not laws — prefer the smallest useful workflow, and if one would add more friction than value, do not force it. Strong workflows are opt-in by task fit, not always-on behavior.
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.
File Artifacts = Truth
SDD pipeline v2 uses per-spec layout:
docs/plans/<spec-id>/<YYYY-MM-DD>/design.md → Design documentsspecs/<spec-id>/spec.xml + specs/<spec-id>/details/*.xml → Refined specificationsspecs/<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.
Skill Priority
When multiple skills could apply, choose the smallest useful one:
- Clarify intent —
arc-brainstorming when requirements or decisions are unclear.
- Formalize source of truth —
arc-refining when converting a design/decision log into structured specs.
- Plan work —
arc-planning when a refined spec needs an implementation DAG.
- Execute work —
arc-coordinating, arc-dispatching-teammates, arc-looping, or arc-implementing based on DAG/worktree context.
- 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.
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 + single task-reviewer, both verdicts) |
| 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, or review feedback received | arc-reviewing | Request review, then process feedback with technical rigor |
| 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
Four 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 the learning-candidate queue, or confirm/contradict auto-detected instincts (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, read-only inspection, harness/eval/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, or outside ArcForge's domain. Proceed directly, and only mention ArcForge skills if they materially help.
Platform Adaptation
Skills describe actions in vendor-neutral terms ("dispatch a subagent", "search the web"). If your harness is not Claude Code, read its reference for the real tool names — Codex: references/codex-tools.md.
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.
