# arcforge Skills Reference

This is the offline reference for all 33 arcforge skills. In a live session, **`arc-using` is the canonical router** — invoke it when you want arcforge to map your situation to a skill; use this document when you want to read about skills in depth.

## Table of Contents

- [Quick Start](#quick-start)
- [Skill Categories](#skill-categories)
- [Complete Skill Catalog](#complete-skill-catalog)
  - Planning: [arc-brainstorming](#arc-brainstorming) · [arc-refining](#arc-refining) · [arc-writing-tasks](#arc-writing-tasks) · [arc-planning](#arc-planning)
  - Execution: [arc-executing-tasks](#arc-executing-tasks) · [arc-agent-driven](#arc-agent-driven) · [arc-implementing](#arc-implementing) · [arc-dispatching-parallel](#arc-dispatching-parallel) · [arc-dispatching-teammates](#arc-dispatching-teammates) · [arc-looping](#arc-looping)
  - Coordination: [arc-using](#arc-using) · [arc-using-worktrees](#arc-using-worktrees) · [arc-compacting](#arc-compacting) · [arc-coordinating](#arc-coordinating) · [arc-finishing](#arc-finishing) · [arc-managing-sessions](#arc-managing-sessions)
  - Quality: [arc-tdd](#arc-tdd) · [arc-debugging](#arc-debugging) · [arc-verifying](#arc-verifying) · [arc-evaluating](#arc-evaluating) · [arc-requesting-review](#arc-requesting-review) · [arc-receiving-review](#arc-receiving-review)
  - Learning: [arc-journaling](#arc-journaling) · [arc-reflecting](#arc-reflecting) · [arc-learning](#arc-learning) · [arc-observing](#arc-observing) · [arc-recalling](#arc-recalling) · [arc-researching](#arc-researching)
  - Knowledge Base: [arc-maintaining-obsidian](#arc-maintaining-obsidian) · [arc-diagramming-obsidian](#arc-diagramming-obsidian)
  - Meta: [arc-writing-skills](#arc-writing-skills) · [arc-auditing-spec](#arc-auditing-spec)
- [Workflow Patterns](#workflow-patterns)
- [Comparison Tables](#comparison-tables)
- [Operating Principles](#operating-principles)
- [Living SDD Responsibility Boundary](#living-sdd-responsibility-boundary)

## Quick Start

arcforge is a minimal, composable skill toolkit for Claude Code, Codex, Gemini CLI, and OpenCode. Skills are structured workflow guides that add discipline when useful while preserving direct answers, read-only inspection, and harness/eval isolation when workflow would be overhead.

> **Platform support**: Core workflow, worktree, and quality skills work on all four platforms. A handful of skills are currently Claude Code-only because they integrate with platform-specific features (session transcripts, subprocess spawning, tool-call logs, agent teammates). Look for **Platform:** markers in each skill's entry below. Today the Claude Code-only skills are: `arc-looping`, `arc-dispatching-teammates`, `arc-evaluating`, `arc-observing`, and `arc-managing-sessions`.

**Core skills every user should learn first:**

1. **arc-using** — Bounded router and skill index for ArcForge tasks
2. **arc-brainstorming** — Design exploration when intent is unclear
3. **arc-refining** — Convert design decisions into structured specs
4. **arc-planning** — Break refined specs into a DAG
5. **arc-tdd** — Test-driven implementation discipline
6. **arc-debugging** — Systematic root cause investigation
7. **arc-verifying** — Fresh evidence before completion claims
8. **arc-evaluating** — Measure whether skills and workflows change behavior

**What are you trying to do?**

```
What are you trying to do?
|
+-- Build something new?
|   +-- Have a spec? --> arc-writing-tasks
|   +-- Need to explore? --> arc-brainstorming
|
+-- Fix a bug?
|   +-- arc-debugging --> arc-tdd --> arc-verifying
|
+-- Understand the system?
|   +-- arc-using (when routing help is useful)
|
+-- Improve workflow?
    +-- arc-journaling --> arc-reflecting
```

---

## Skill Categories

arcforge's 33 skills are organized into a three-layer model:

1. **Core toolkit** — the small promoted surface most users should learn first.
2. **Optional workflows** — recipes and advanced orchestration used only when the task justifies them.
3. **Harness/eval layer** — tests and evaluation skills that verify both activation and non-activation behavior.

The complete catalog still uses functional categories for lookup:

| Category | Skills | Purpose |
|----------|--------|---------|
| **Planning** | arc-brainstorming, arc-refining, arc-writing-tasks, arc-planning | Explore, specify, break down |
| **Execution** | arc-executing-tasks, arc-agent-driven, arc-implementing, arc-dispatching-parallel, arc-dispatching-teammates, arc-looping | Build and ship |
| **Coordination** | arc-using, arc-using-worktrees, arc-coordinating, arc-finishing, arc-compacting, arc-managing-sessions | Route, isolate, integrate |
| **Quality** | arc-tdd, arc-debugging, arc-verifying, arc-requesting-review, arc-receiving-review, arc-evaluating | Test, debug, verify, review |
| **Learning** | arc-journaling, arc-reflecting, arc-learning, arc-observing, arc-recalling, arc-researching | Capture, extract, evolve |
| **Knowledge Base** | arc-maintaining-obsidian, arc-diagramming-obsidian | Ingest, query, audit, and visualize an Obsidian vault |
| **Meta** | arc-writing-skills, arc-auditing-spec | Maintain ArcForge's own skills; audit SDD spec families |

**How skills flow through a project:**

```
  PLANNING          EXECUTION         COORDINATION
  --------          ---------         ------------
  brainstorming --> writing-tasks --> executing-tasks --> finishing
  refining -------> planning -------> implementing ----> finishing-epic
                    |                 |
                    v                 v
                    agent-driven      dispatching-parallel
                    |
                    +--- using-worktrees, coordinating

  QUALITY                   LEARNING              META
  -------                   --------              ----
  tdd (during execution)    journaling            writing-skills
  debugging (on failure)    reflecting
  verifying (before done)   learning
  evaluating (skill eval)   observing
  requesting-review         recalling
  receiving-review          researching
```

---

## Complete Skill Catalog

### Planning Skills

---

### arc-brainstorming

**Purpose:** Explore ideas before implementation through structured discovery and design.

**When to use:** When exploring ideas before implementation or when user says "let's build X".

**Key workflow:**
1. Phase 0 Scan and Route — list `specs/<spec-id>/` directories; user confirms new topic vs. iterating on existing spec-id
2. Understand context — check project state, ask questions one at a time
3. Explore approaches — propose 2-3 options with trade-offs, apply YAGNI
4. Present design — 200-300 word sections, confirm each with user
5. Write design doc to `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md` (prose for new topic; Context + Change Intent for iteration). Design doc MUST NOT carry a pre-authored delta — refiner is the delta authority.
6. Route to next skill (refining → planning → coordinating)

**Artifacts:**
- Output: `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md`
- Intermediate: `docs/research/<topic>.md` (2-Action Rule saves)

**Related:** nothing required --> **arc-brainstorming** --> arc-refining (complex) or arc-writing-tasks (simple)

---

### arc-refining

**Purpose:** Transform design documents into structured XML specifications that serve as the single source of truth.

**When to use:** When converting design documents to structured specs, when spec quality is below threshold, or when requirements need formal acceptance criteria.

**Key workflow:**
1. Validate design doc via `parseDesignDoc` + `validateDesignDoc` from `scripts/lib/sdd-utils.js`
2. DAG completion gate (when prior spec exists): block if any epic in `specs/<spec-id>/dag.yaml` is not `completed`
3. Detect context from filesystem: `specs/<spec-id>/spec.xml` exists → iteration (expect Context + Change Intent sections); missing → v1 formalization (expect prose)
4. Two-pass write: build spec in memory, validate via `parseSpecHeader` + `validateSpecHeader`, atomic write only if zero ERRORs
5. Append new `<delta>` as last child of `<overview>`; preserve every prior `<delta>` verbatim
6. Commit specs to git

**Artifacts:**
- Input: `docs/plans/<spec-id>/<YYYY-MM-DD>/design.md` (from arc-brainstorming)
- Output: `specs/<spec-id>/spec.xml`, `specs/<spec-id>/details/*.xml`

**Related:** arc-brainstorming --> **arc-refining** --> arc-planning

---

### arc-writing-tasks

**Purpose:** Break features into bite-sized (2-5 minute) tasks with exact code and commands.

**When to use:** When breaking down features into executable tasks, when preparing for implementation, or when tasks need exact code and commands.

**Key workflow:**
1. Read feature spec or design document
2. Identify files needed
3. Break into 2-5 minute tasks with exact code (not "add validation")
4. Add test commands with expected output per task
5. Output task list in TDD order (test first, then implementation)

**Artifacts:**
- Input: design doc, feature spec, or epic.md
- Output: `docs/tasks/<feature-name>-tasks.md`

**Related:** arc-brainstorming or arc-refining --> **arc-writing-tasks** --> arc-executing-tasks or arc-agent-driven

---

### arc-planning

**Purpose:** Convert specs into an executable DAG with epic/feature breakdown and strict 1:1 traceability.

**When to use:** When breaking down specifications, when `specs/<spec-id>/spec.xml` exists, or when planning epic and feature structure.

**Key workflow:**
1. Verify `specs/<spec-id>/spec.xml` and `specs/<spec-id>/details/` exist (else route to arc-refining)
2. Extract sprint scope via `parsed.latest_delta` (v2+ spec) or all requirements (v1 spec)
3. Map each delta child to one epic: `<added>` implement, `<modified>` update, `<removed>` teardown, `<renamed>` mechanical refactor
4. Self-validate (no cycles, all references valid, pure function — no design doc read, no archive)
5. Overwrite `specs/<spec-id>/dag.yaml` — previous statuses MUST NOT carry over; every epic starts `pending`
6. Commit `specs/<spec-id>/dag.yaml` and `specs/<spec-id>/epics/` to git

**Artifacts:**
- Input: `specs/<spec-id>/spec.xml`, `specs/<spec-id>/details/*.xml`
- Output: `specs/<spec-id>/dag.yaml`, `specs/<spec-id>/epics/<epic-name>/epic.md`, `specs/<spec-id>/epics/<epic-name>/features/*.md`

**Related:** arc-refining --> **arc-planning** --> arc-coordinating or arc-implementing

---

### Execution Skills

---

### arc-executing-tasks

**Purpose:** Human-in-the-loop task execution with batch checkpoints and verification.

**When to use:** When executing a prepared task list, when running batch implementation, or when tasks are already broken down.

**Key workflow:**
1. Load and review task file from `docs/tasks/`
2. Execute in batches (default 3 tasks per batch)
3. Follow TDD steps exactly for each task
4. Present checkpoint report after each batch — wait for feedback
5. Continue or adjust based on feedback
6. Use arc-finishing when all tasks complete

**Artifacts:**
- Input: `docs/tasks/<name>-tasks.md`
- Output: committed code, checkpoint reports

**Related:** arc-writing-tasks --> **arc-executing-tasks** --> arc-finishing

---

### arc-agent-driven

**Purpose:** Fully autonomous task execution with fresh subagent per task and two-stage review.

**When to use:** When executing task lists where each task requires isolated execution.

**Key workflow:**
1. Read task list, create TodoWrite tracking
2. Per task: dispatch implementer subagent with full task text
3. Spec compliance review (dispatch reviewer subagent)
4. Code quality review (dispatch reviewer subagent)
5. Max 3 review cycles per reviewer — escalate to human if not converging
6. After all tasks: dispatch final code reviewer, then arc-finishing

**Artifacts:**
- Input: `docs/tasks/<name>-tasks.md`
- Output: committed code per task, review reports

**Related:** arc-writing-tasks --> **arc-agent-driven** --> arc-finishing

---

### arc-implementing

**Purpose:** Orchestrator for large projects — automatically expands epic to features to tasks to execution.

**When to use:** When orchestrating large project implementation in a worktree.

**Key workflow:**
1. Phase 0: Sync and check dependencies via arc-coordinating
2. Phase 1: Epic to features via arc-writing-tasks
3. Phase 2a: Feature to tasks via arc-writing-tasks (max 2 refinement cycles)
4. Phase 2b: Execute tasks via arc-agent-driven
5. Phase 3: Move to next feature or finish epic

**Artifacts:**
- Input: `specs/<spec-id>/dag.yaml`, `specs/<spec-id>/epics/<epic-name>/epic.md`, `specs/<spec-id>/epics/<epic-name>/features/*.md`
- Output: completed code via delegated skills

**Related:** arc-planning + arc-coordinating --> **arc-implementing** --> arc-finishing (epic path)

---

### arc-dispatching-parallel

**Purpose:** Dispatch multiple agents for independent tasks in parallel.

**When to use:** When dispatching multiple independent features within a worktree session.

**Key workflow:**
1. Identify independent tasks (no shared dependencies or files)
2. Create focused prompts with specific scope and constraints
3. Dispatch agents in parallel via Task tool
4. Review and integrate — verify no conflicts, run full test suite
5. If conflicts found: tasks were not truly independent — resolve manually

**Artifacts:**
- Input: `specs/<spec-id>/dag.yaml` (DAG-based) or list of independent failures (without DAG)
- Output: parallel fixes integrated, test suite passing

**Related:** arc-planning --> **arc-dispatching-parallel** --> arc-implementing

---

### arc-dispatching-teammates

**Platform:** Claude Code only — requires the agent teammates feature (Claude Code 2.1.32+) and the Agent tool's `team_name`/`name` parameters. Other platforms have no equivalent multi-worker coordination substrate.

**Purpose:** Dispatch one Claude Code agent teammate per ready epic so the lead session stays in control while multiple epics progress in parallel. Fills the gap between `arc-coordinating` (single-epic interactive) and `arc-looping` (multi-epic unattended).

**When to use:** When `specs/<spec-id>/dag.yaml` has 2+ epics in a ready state AND the user is staying at the keyboard to monitor (not walking away). The discriminator against `arc-looping` is **attendance, not risk** — a risky epic with the lead watching is still teammates; a safe epic with the lead walking away is still `arc-looping`.

**Key workflow:**
1. Verify preconditions: 2+ ready epics, Agent tool supports `team_name`, lead in project root (not inside a worktree)
2. Cap team size at 5 — if more ready epics, queue the rest for continuous dispatch
3. `TeamCreate` before any Agent dispatch (passing `team_name` to Agent does NOT auto-create)
4. Per epic: `arcforge expand --epic <id>` → read canonical worktree path → spawn teammate with spawn prompt template (parallel dispatch, sequential retry on GH #40168 timing race)
5. Monitor via SendMessage — dispatch queued epics into freed slots as teammates complete (continuous, not waves)
6. **Acceptance check** per teammate completion: dispatch `arcforge:spec-reviewer` + `arcforge:verifier` subagents with fresh context. Both PASS = accept and shut down teammate; either FAIL = Step 7. Lead reads reports and decides — does NOT run checks inline
7. **Retry loop** on rejection: up to 3 retries per epic with cumulative feedback. Fresh worktree from dev HEAD (fix-forward), dispatch retry teammate. Spec-defect overrides (spec references wrong file/path) skip retry via override-accept protocol
8. **Wrap up** when all epics reach terminal state: emit Final Report with per-epic subagent evidence, cleanup accepted worktrees, shut down remaining teammates, `TeamDelete`

**Artifacts:**
- Input: `specs/<spec-id>/dag.yaml` (required), `skills/arc-dispatching-teammates/SKILL.md`
- Output: per-epic worktrees at `~/.arcforge/worktrees/...`, one agent teammate per ready epic, merged epics via each teammate's own finishing step, Final Report with subagent evidence
- Progressive-loading references: `acceptance-and-retry.md`, `spawn-prompt-template.md`, `tmux-timing-race.md`, `wrap-up-sequence.md`

**Related:** arc-planning → **arc-dispatching-teammates** → (per completion: spec-reviewer + verifier subagents); each teammate runs arc-implementing → arc-finishing (epic path) on its own

---

### arc-looping

**Platform:** Claude Code only — spawns fresh sessions via `claude -p` subprocess. Other platforms have no equivalent invocation mechanism (yet).

**Purpose:** Run arcforge workflows autonomously across sessions — each iteration spawns a fresh Claude session while DAG and git persist state.

**When to use:** When tasks can run fully unattended across sessions with no human judgment needed per task.

**Key workflow:**
1. Verify DAG exists (from arc-planning) and baseline tests pass
2. Choose loop pattern: sequential (safest, one task at a time) or DAG (parallel-aware)
3. Set bounds: `--max-runs` and optional `--max-cost`
4. Start loop: `node scripts/cli.js loop --pattern sequential --max-runs 20`
5. Each iteration: read dag.yaml, spawn fresh Claude session, execute task, update DAG
6. Stop on: all complete, max-runs hit, cost limit, stall detected, or retry storm

**Artifacts:**
- Input: `specs/<spec-id>/dag.yaml` (required, must be committed)
- Output: `.arcforge-loop.json` (loop state tracking), committed code per completed task

**Related:** arc-planning --> **arc-looping** --> arc-finishing

---

### Coordination Skills

---

### arc-using

**Purpose:** Bounded router and skill index for ArcForge tasks — helps choose the smallest useful workflow without becoming a global policy layer.

**When to use:** When an ArcForge task needs routing help, when the user asks which skill/workflow applies, or when task scope is ambiguous enough that a skill choice matters.

**Key workflow:**
1. Understand the user request and constraints
2. Decide whether routing adds value; skip routing for simple answers, read-only inspection, grading, or isolated evals
3. If useful, pick the smallest applicable skill or workflow path
4. Read/invoke only the relevant skill(s)
5. Preserve harness/eval isolation and higher-priority instructions

**Artifacts:**
- Input: user request that benefits from routing
- Output: selected skill(s) or direct continuation when routing is unnecessary

**Related:** optional session bootstrap --> **arc-using** --> any applicable skill, or direct task execution

---

### arc-using-worktrees

**Purpose:** Isolated git worktrees for **any** repo, in two tiers. A
**generic tier** (`arcforge worktree add|list|remove`) handles a parallel
branch, an experiment, or a review checkout in any project; a **composition
tier** hands single-epic work to the coordinator. Both derive the canonical
path at runtime — you never invent one.

**When to use:** When work needs an isolated workspace — a parallel branch,
an experiment, a review checkout, or scoping to one epic — in any git repo.

**Key workflow (top-down, first match wins):**
1. `.arcforge-epic` exists in cwd → already inside an epic worktree; never
   nest. Work → arc-implementing; integration → arc-finishing.
2. `specs/<id>/dag.yaml` exists and the work matches an epic id → composition
   tier: escalate to the coordinator (`arcforge expand --epic <id>`).
3. Anything else (a branch, experiment, or review checkout) → generic tier:
   `arcforge worktree add <name>`, then read the absolute `path` from the
   JSON output and `cd` there.

**Artifacts:**
- Generic: a managed worktree at `~/.arcforge/worktrees/<project>-<hash>-<slug>/`
  with **no** marker (`kind: generic`)
- Epic (composition tier): worktree + `.arcforge-epic` marker authored by the
  coordinator, `dag.yaml` epic status updated

For the full derivation rules — including the generic null-spec path, kind
annotation, and the sync/merge invisibility guarantee — see
[`docs/guide/worktree-workflow.md`](worktree-workflow.md) and the Worktree
Rule in `skills/arc-using/SKILL.md`.

**Related:** arc-planning --> **arc-using-worktrees** --> arc-implementing or arc-executing-tasks

---

### arc-compacting

**Purpose:** Guide compaction decisions at logical workflow boundaries instead of letting auto-compaction fire mid-task.

**When to use:** When the compact-suggester hook fires, when transitioning between workflow phases, or when a long session has accumulated stale context.

**Key workflow:**
1. Check phase transition — compact between phases (when state is persisted to files), not during
2. Pre-compact: save decisions to files/memory, invoke `arc-journaling` if session was substantial
3. Check for un-committed work — ensure valuable changes are committed
4. Compact with focused seed text: `/compact Focus on implementing [next task]`
5. Post-compact: run `arcforge reboot`, re-read needed files

**Artifacts:**
- Input: session context, rule files, memory files
- Output: compacted context focused on next phase

**Related:** compact-suggester hook --> **arc-compacting** --> arc-agent-driven, arc-planning

---

### arc-coordinating

**Purpose:** CLI-based worktree lifecycle management and cross-session coordination via Node.js.

**When to use:** When managing worktrees for multi-epic projects, when `specs/<spec-id>/dag.yaml` exists, or when coordinating parallel development.

**Key workflow:**
1. Set SKILL_ROOT from skill loader header
2. Use `node "${SKILL_ROOT}/scripts/coordinator.js" <command>`
3. Commands: expand, merge, status, cleanup, sync, next, parallel, block, reboot

**Artifacts:**
- Input: `specs/<spec-id>/dag.yaml` (required, must be committed)
- Output: worktrees created/merged, DAG status updated

**Related:** arc-planning --> **arc-coordinating** --> arc-implementing

---

### arc-finishing

**Purpose:** Guide completion of development work with structured options. One skill, two paths — Step 0 discriminates on `.arcforge-epic`: an **epic path** (coordinator integration + DAG updates for marker'd worktrees) and a **non-epic path** (plain git for regular branches and generic worktrees).

**When to use:** When implementation is complete and all tests pass, and you need to decide how to integrate — whether in an epic worktree (`.arcforge-epic` present) or on a regular branch.

**Key workflow:**
1. Step 0 — read `.arcforge-epic` to pick the path (epic vs non-epic)
2. Epic path only: sync from base via finish-epic.js
3. Verify all tests pass (auto-detect test command)
4. Determine base branch
5. Present 4 options: merge (epic: via coordinator; non-epic: into the base checkout), create PR, keep as-is, discard
6. Look up the worktree path (epic: `status --json` on the base dag; non-epic: `worktree list --json`)
7. Cleanup worktree for Options 1 and 4 only (cd to base first)

**Artifacts:**
- Input: completed branch or epic worktree with passing tests
- Output: merged code/epic, PR, preserved branch, or discarded work (+ DAG updated on the epic path)

**Related:** arc-executing-tasks / arc-agent-driven / arc-implementing --> **arc-finishing** --> done / arc-coordinating status

---

### arc-managing-sessions

**Platform:** Claude Code only — uses Claude Code's session IDs, transcript format, and the `~/.arcforge/sessions/` directory layout.

**Purpose:** User-controlled session saves for continuity across conversations — save what matters, resume when needed.

**When to use:** When saving session state for cross-conversation handoff, resuming a previous session, listing session history, or managing session aliases.

**Key workflow:**
1. **Save:** Reflect on conversation, write enrichment (summary, what worked/failed, blockers, next step), save to session file
2. **Resume:** Resolve alias, read session file, present structured briefing, WAIT for user confirmation
3. **List:** Browse sessions with filters (`--limit`, `--date`, `--query`)
4. **Alias:** Create friendly names for easy session reference

**Artifacts:**
- Input: current session data from `~/.arcforge/sessions/{project}/{date}/{sessionId}.json`
- Output: `~/.arcforge/sessions/{project}/{date}/session-{alias}.md`, `aliases.json`

**Related:** any skill --> **arc-managing-sessions** (when continuity is needed)

---

### Quality Skills

---

### arc-tdd

**Purpose:** Enforce test-driven development: write the test first, watch it fail, write minimal code to pass.

**When to use:** When implementing any feature or bugfix, before writing implementation code.

**Key workflow:**
1. Find similar implementations first (reference before building)
2. RED — write one minimal failing test showing desired behavior
3. Verify RED — watch it fail for the expected reason
4. GREEN — write simplest code to pass the test
5. Verify GREEN — all tests pass, output pristine
6. REFACTOR — clean up while keeping tests green

**Artifacts:**
- Input: feature spec or bug report
- Output: test file + implementation, both committed

**Related:** arc-writing-tasks --> **arc-tdd** (during execution) --> arc-verifying

---

### arc-debugging

**Purpose:** Systematic root cause investigation using a four-phase scientific method.

**When to use:** When encountering any bug, test failure, or unexpected behavior, before proposing fixes.

**Key workflow:**
1. Phase 1: Root Cause Investigation — read errors, reproduce, check recent changes, trace data flow
2. Phase 2: Pattern Analysis — find working examples, compare differences
3. Phase 3: Hypothesis and Testing — form single hypothesis, test minimally, one variable at a time
4. Phase 4: Implementation — create failing test, implement single fix, verify
5. If 3+ fixes fail: STOP and question the architecture

**Artifacts:**
- Input: bug report, test failure, or unexpected behavior
- Output: root cause identified, failing test, verified fix

**Related:** any failure --> **arc-debugging** --> arc-tdd --> arc-verifying

---

### arc-verifying

**Purpose:** Evidence-first verification mindset — no completion claims without fresh verification evidence.

**When to use:** When you need to verify work is complete before making completion claims.

**Key workflow:**
1. IDENTIFY — what command proves this claim?
2. RUN — execute the full command fresh
3. READ — full output, check exit code, count failures
4. VERIFY — does output confirm the claim?
5. ONLY THEN — make the claim with evidence

**Artifacts:**
- Input: any completion claim
- Output: verified status with evidence (test output, build output, etc.)

**Related:** embedded in all skills as a mindset, especially arc-finishing, arc-tdd

---

### arc-evaluating

**Platform:** Claude Code only — eval harness invokes `claude` subprocess to execute scenario trials.

**Purpose:** Measure whether skills, agents, and workflows actually change AI agent behavior — unit tests for AI agent behavior.

**When to use:** Before shipping a new skill, after modifying an existing one, or when comparing alternative approaches.

**Key workflow:**
1. Confirm eval scope with user: skill (behavior change), agent (task outcome), or workflow (toolkit effect)
2. Define the question first: "What are you trying to learn?"
3. Design scenario with assertions and grader type (code, model, or human)
4. Run scenario validity preflight (expected baseline failure, ceiling/floor risk, answer leakage)
5. Run eval trials (`arc eval run` or `arc eval ab` for A/B comparison)
6. Grade results, track in JSONL, report verdict: SHIP / NEEDS WORK / BLOCKED

**Artifacts:**
- Input: scenario files in `evals/scenarios/`
- Output: benchmark results in `evals/benchmarks/latest.json`, eval reports

**Related:** arc-brainstorming --> **arc-evaluating** --> arc-writing-skills (for shipping)

---

### arc-requesting-review

**Purpose:** Structured code review requests with proper context for reviewer subagents.

**When to use:** When completing tasks or features to request code review.

**Key workflow:**
1. Get git SHAs (base and head)
2. Dispatch code-reviewer subagent with filled template placeholders
3. Act on feedback: fix Critical immediately, Important before proceeding, note Minor

**Artifacts:**
- Input: completed task with commits
- Output: review feedback, fixes applied

**Related:** arc-agent-driven --> **arc-requesting-review** --> arc-receiving-review

---

### arc-receiving-review

**Purpose:** Handle code review feedback with technical rigor, not performative agreement.

**When to use:** When receiving code review feedback, requires technical rigor not performative agreement.

**Key workflow:**
1. READ — complete feedback without reacting
2. UNDERSTAND — restate requirement in own words
3. VERIFY — check against codebase reality
4. EVALUATE — technically sound for THIS codebase?
5. RESPOND — technical acknowledgment or reasoned pushback
6. IMPLEMENT — one item at a time, test each

**Artifacts:**
- Input: review feedback
- Output: verified fixes or reasoned pushback

**Related:** arc-requesting-review --> **arc-receiving-review** --> continue or arc-verifying

---

### Learning Skills

---

### arc-journaling

**Purpose:** Capture session reflections as structured diary entries for future pattern extraction.

**When to use:** When the user asks to journal session reflections (/arcforge:arc-journaling), when PreCompact hook triggers, or at end of significant work session.

**Key workflow:**
1. Pre-diary check — verify session had non-trivial decisions or challenges
2. Reflect on conversation from memory (do NOT read files)
3. Fill template: decisions, preferences, challenges, solutions
4. Save to `~/.arcforge/diaries/{project}/{date}/diary-{sessionId}.md`
5. Offer follow-up: "run `/arcforge:arc-reflecting` to extract patterns"

**Artifacts:**
- Output: `~/.arcforge/diaries/{project}/{YYYY-MM-DD}/diary-{sessionId}.md`

**Related:** **arc-journaling** --> arc-reflecting (after 5+ entries)

---

### arc-reflecting

**Purpose:** Analyze multiple diary entries to identify recurring patterns and save insights.

**When to use:** When the user asks to reflect on accumulated diaries (/arcforge:arc-reflecting), after 5+ diary entries accumulate, or when asked to summarize preferences from past sessions.

**Key workflow:**
1. Smart filter selection (unprocessed, project_focused, or recent_window)
2. Read CLAUDE.md rules to detect violations
3. Read and analyze diary entries for patterns
4. Identify patterns (3+ occurrences) vs observations (1-2)
5. Save reflection + instincts, update processed.log

**Artifacts:**
- Input: `~/.arcforge/diaries/{project}/*/diary-*.md`
- Output: `~/.arcforge/diaryed/{project}/YYYY-MM-reflection-N.md`, instinct files

**Related:** arc-journaling (5+ entries) --> **arc-reflecting** --> arc-learning (dashboard review)

---

### arc-learning

**Purpose:** Review observer-curated learning candidates and turn them into activated artifacts through the dashboard.

**When to use:** When optional learning is enabled and you want to review the candidate instincts the observer daemon's LLM curator has proposed.

**Key workflow:**
1. Enable learning: `arcforge learn enable --project`
2. Open the dashboard: `arcforge learn dashboard` (port 3334)
3. Review queued candidates (`pending_review` → `approved` → `materialized` → `activated`)
4. Authorize through three gates: Approve → Materialize → Activate (no candidate changes behavior without explicit action)
5. Promote / Evolve / Deactivate as needed (Promote and Evolve mint new candidates; silent auto-promotion is not supported)

**Artifacts:**
- Input: `~/.arcforge/learning/candidates/queue.jsonl` (Layer 5 candidate queue)
- Output: `~/.arcforge/learning/drafts/` (Layer 7 inactive drafts) → `~/.arcforge/instincts/<scope>/` (Layer 8 activation)

**Related:** arc-observing (curates candidates) --> **arc-learning** (dashboard review)

> The pre-pivot `arcforge learn analyze` statistical clustering (Jaccard, confidence thresholds) was retired in v3.1 — see [learning-dashboard.md](learning-dashboard.md).

---

### arc-observing

**Platform:** Claude Code only — reads Claude Code tool-call observations from `~/.arcforge/observations/` which is populated by Claude Code PostToolUse hooks.

**Purpose:** Capture tool-usage observations and feed them into the post-pivot four-layer curation pipeline.

**When to use:** When user asks about behavioral patterns, requests learning status, or wants to manage the observer daemon.

**Key workflow:**
1. Capture: hooks record every tool call to observations.jsonl (skip filter honored)
2. Batch assembly (Layer 3): daemon calls `assemble-batch` on a batch of sanitized observations
3. LLM curation (Layer 4): Haiku curator with `--json-schema` produces candidate proposals (failure → `transport_error` / `timeout` manifest)
4. Ingestion (Layer 5): `ingest-proposal` validates proposals into the candidate queue
5. Review: candidates are acted on in the dashboard; SessionStart never auto-loads instinct bodies

**Artifacts:**
- Input: `~/.arcforge/observations/{project}/observations.jsonl`
- Output: `~/.arcforge/learning/candidates/queue.jsonl` (candidate proposals — the daemon no longer writes instinct `.md` files directly)

**Related:** background daemon --> **arc-observing** --> arc-learning (dashboard review)

---

### arc-recalling

**Purpose:** Manually save patterns and insights as instincts from the current session context.

**When to use:** When the user wants to manually save a pattern or insight as an instinct. When the user invokes /arcforge:arc-recalling with a description.

**Key workflow:**
1. Receive user's natural language description
2. Infer structured fields: id, trigger, action, domain, evidence
3. Preview instinct for user confirmation
4. Check for duplicates
5. Save with source: manual, confidence: 0.50

**Artifacts:**
- Input: user-described pattern or insight
- Output: `~/.arcforge/instincts/{project}/<id>.md`

**Related:** user insight --> **arc-recalling** --> instinct saved for arc-observing lifecycle

---

### arc-researching

**Purpose:** Autonomous hypothesis-driven experimentation to optimize any measurable metric — build times, algorithm efficiency, prompt quality, or any target with a numeric signal.

**When to use:** When optimizing a measurable metric through free-form experimentation rather than a predefined task list.

**Key workflow:**
1. Phase 1 (Interactive): Analyze target, propose `research-config.md` contract (scope, goal, evaluation, constraints), lock with user
2. Phase 2: Create research branch, run evaluation, establish baseline metric, start dashboard
3. Phase 3 (Autonomous loop): Hypothesize, implement, commit, run, extract metric, keep or revert, log to `results.tsv`
4. Decision rules: improved = keep, same/worse = revert, crash = log + revert
5. Stuck protocol: 3+ failures in same direction, change direction entirely
6. Phase 4: Report baseline, best result, improvement %, experiment counts

**Artifacts:**
- Input: measurable metric, target files, evaluation command
- Output: `research-config.md` (locked contract), `results.tsv` (untracked), `research/{tag}` branch

**Related:** arc-brainstorming --> **arc-researching** --> manual cherry-pick to main

---

### Knowledge Base Skills

---

### arc-maintaining-obsidian

**Platform:** All platforms. Requires an Obsidian vault; `obsidian-cli` is preferred for vault operations but the skill falls back to direct file writes when the CLI is unavailable.

**Purpose:** Unified Obsidian vault lifecycle skill — one agent, three modes (ingest, query, audit) — implementing Karpathy's LLM Wiki pattern for a persistent, compounding knowledge base. Eliminates wiki maintenance burden by handling classification, schema compliance, propagation, and gap analysis as a single shared-context operation.

**When to use:** When creating, querying, or maintaining an Obsidian vault. Triggers on saving notes, capturing ideas/decisions, sharing URLs to document, asking vault questions ("what do I know about X"), auditing vault health (missing links, orphan notes, stale content), or ingesting raw files (Excalidraw, PDFs, screenshots, papers).

**Key workflow:**
- **Ingest** pipeline: `Classify → Confirm → Create → Visuals → Index → Propagate → Log` — 6 page types (Source, Entity, Synthesis, MOC, Decision, Log) + Paper variant for academic papers. Raw-first-then-wiki rule preserves re-extraction ability.
- **Query** pipeline: `Orient → Search → Read → Synthesize → (File Back)` — vault-only answers (no general-knowledge backfill), inline citations, optional file-back as a new synthesis note.
- **Audit** pipeline: `LINK → LINT → GROW` — resolve plain-text mentions into wikilinks, schema/orphan/stale checks with `index.md` rebuild, gap analysis with internal and external suggestions.

**Artifacts:**
- Input: URLs, files, text descriptions, natural-language queries
- Output: typed wiki notes with bilingual `[!multi-lang-{code}]` callout format, audit reports under `audit-YYYY-MM-DD-<subcommand>.md`, rolling `index.md` and `log.md`

**Related:** user input --> **arc-maintaining-obsidian** (three modes) --> vault state updated. Delegates Excalidraw creation to **arc-diagramming-obsidian** via the Visuals decision tree.

---

### arc-diagramming-obsidian

**Platform:** All platforms. Requires an Obsidian vault with the Excalidraw community plugin installed.

**Purpose:** Create Excalidraw diagrams directly in an Obsidian vault via structured JSON write with a render-validate loop, applying a cool minimal color palette for visual consistency.

**When to use:** When the user wants an Excalidraw diagram, architecture visualization, flowchart, mind map, or any visual representation of concepts and relationships. Trigger on mentions of drawing, diagramming, visualizing, mapping, or illustrating — especially when `arc-maintaining-obsidian`'s Visuals decision tree routes here for complex spatial layouts.

**Key workflow:**
1. Identify target concept and relationships (nodes + edges)
2. Draft Excalidraw JSON with positions, groups, and color palette
3. Write the `.excalidraw.md` file into the vault's Excalidraw folder
4. Render-validate loop: open in Obsidian, verify layout, iterate on positioning
5. Return the vault path for embedding in a Source note

**Artifacts:**
- Input: concept description, existing vault note to visualize, or relationship graph
- Output: `.excalidraw.md` file in the vault's Excalidraw folder, ready for embedding via `![[filename]]`

**Related:** arc-maintaining-obsidian (Visuals step, Q4 spatial complexity) --> **arc-diagramming-obsidian** --> diagram embedded in the originating note

---

### Meta Skills

---

### arc-writing-skills

**Purpose:** ArcForge project-level meta skill for maintaining ArcForge's own skill system using TDD for process documentation.

**When to use:** When maintaining ArcForge itself: creating new ArcForge skills, editing existing ArcForge skills, or verifying ArcForge skills before deployment. This is not a general promoted/user-facing core skill for ordinary product work.

**Key workflow:**
1. RED — run pressure scenario WITHOUT skill, document baseline failures
2. GREEN — write minimal SKILL.md addressing specific rationalizations found
3. REFACTOR — find new loopholes, add counters, re-test until the skill behavior is covered
4. Validate: frontmatter (name + description only, max 1024 chars, "Use when...")
5. Run pytest validation and commit skill changes

**Artifacts:**
- Input: baseline test results showing agent failures
- Output: `skills/<skill-name>/SKILL.md`, pytest test file

**Related:** ArcForge maintainer task --> **arc-writing-skills** --> deployed ArcForge skill

---

### arc-auditing-spec

**Purpose:** Read-only advisory audit of an SDD spec family (design.md, spec.xml, dag.yaml, decisions.yml, product/vision.md) across three axes: internal consistency, cross-artifact alignment, and state-transition integrity.

**When to use:** When the user explicitly runs `/arcforge:arc-auditing-spec <spec-id>`. Never auto-invoked from pipeline skills (arc-brainstorming, arc-refining, arc-planning) — invocation is always user-initiated.

**Key workflow:**
1. Phase 0 — verify `specs/<spec-id>/` exists (graceful degradation: only design.md is required)
2. Fan out three parallel audit subagents, one per axis
3. Aggregate findings into a single advisory report
4. Print a Decisions table and exit — the skill never edits anything (`--save` optionally writes the report to `~/.arcforge/reviews/`)

**Artifacts:**
- Input: `specs/<spec-id>/` family + D6 anchor artifacts
- Output: advisory report (display only, or saved via `--save`); zero mutations

**Related:** user runs `/arcforge:arc-auditing-spec <spec-id>` --> **arc-auditing-spec** --> main session owns any actual edits

---

## Workflow Patterns

### 1. Small Feature

```
arc-using --> arc-writing-tasks --> arc-executing-tasks --> arc-finishing
                                        |
                                   (if bugs) --> arc-debugging --> arc-tdd
```

Best for single features with clear requirements. Use arc-writing-tasks to break down, execute with human checkpoints, finish when done.

### 2. Large Epic

```
arc-brainstorming --> arc-refining --> arc-planning --> arc-using-worktrees
     |                                     |
     v                                     v
  design.md                            dag.yaml
                                           |
                                           v
                              arc-coordinating --> arc-implementing
                                   |                    |
                                   v                    v
                          arc-dispatching-parallel  arc-agent-driven
                                                        |
                                                        v
                                                  arc-finishing
```

Full workflow for complex projects. Explore design, refine to spec, plan DAG, isolate in worktrees, coordinate parallel epics, implement with subagents.

### 3. Bug Fix

```
arc-debugging --> arc-tdd --> arc-verifying --> arc-finishing
     |                            |
     v                            v
  root cause              evidence collected
  identified              before claiming done
```

Systematic debugging first (no guessing), TDD to fix (failing test proves the bug), verify with evidence before finishing.

### 4. Learning Loop

```
arc-journaling --> arc-reflecting --> arc-learning
     |                  |                 |
     v                  v                 v
  diary entry      patterns found    instincts clustered
```

Capture session insights in diaries, extract patterns after 5+ entries, and cluster related instincts. ArcForge maintainers may separately use `arc-writing-skills` when a proven pattern should become an ArcForge skill.

---

## Comparison Tables

### arc-executing-tasks vs arc-agent-driven

| | arc-executing-tasks | arc-agent-driven |
|---|---|---|
| **Model** | Human-in-the-loop batches | Fully autonomous subagents |
| **Review** | Human reviews each batch | Two-stage automated review |
| **Best for** | Tasks needing judgment | Mechanical tasks with clear specs |
| **Risk** | Slower (human bottleneck) | May diverge without oversight |

### arc-finishing: epic path vs non-epic path

`arc-finishing` is one skill; Step 0 reads `.arcforge-epic` and selects the path.

| | Non-epic path | Epic path |
|---|---|---|
| **Scope** | Regular branch / generic worktree | Worktree with `.arcforge-epic` |
| **DAG** | No DAG involvement | Updates dag.yaml status |
| **Cleanup** | Branch + generic worktree | Worktree + branch (via coordinator) |
| **Trigger** | No `.arcforge-epic` file | `.arcforge-epic` file exists |

### arc-brainstorming vs arc-writing-tasks

| | arc-brainstorming | arc-writing-tasks |
|---|---|---|
| **Input** | Rough idea | Approved design/spec |
| **Output** | design.md | tasks.md with exact code |
| **Mode** | Exploratory, Socratic | Prescriptive, detailed |
| **Requires** | Nothing | Design document |

---

## Operating Principles

These principles keep ArcForge disciplined without making every task follow the same workflow:

1. **Smallest Useful Workflow** — use direct answers for simple/read-only tasks; route only when a skill adds leverage
2. **Explore Before Committing to Design** — arc-brainstorming: research existing patterns before proposing new
3. **No ArcForge Skill Without Failing Test** — arc-writing-skills: project-level TDD for ArcForge skill documentation
4. **No Fix Without Hypothesis** — arc-debugging: Observe, Hypothesize, Test, Fix cycle
5. **No Completion Claim Without Evidence** — arc-verifying: evidence-first verification
6. **Verify Before Implementing Review Feedback** — arc-receiving-review: technical rigor, not performative agreement
7. **File Artifacts = Truth** — Don't rely on session memory; resume from file artifacts

## Living SDD Responsibility Boundary

ArcForge's Living SDD pipeline assigns each spec-related job to exactly one owner. None of these owners absorbs another's job, and none is folded into the SessionStart bootstrap or the `arc-using` router as global always-on policy.

| Owner | Owns | Does not own |
|-------|------|--------------|
| `arc-refining` | Formalizing design docs into authoritative `specs/<spec-id>/spec.xml` + `details/*.xml` | Completion-claim verification; post-implementation spec sync |
| `arc-verifying` | Producing fresh evidence before completion claims | Authoring spec artifacts; reconciling spec/code drift |
| `arc-syncing-spec` (future, optional) | Post-implementation / drift sync of spec artifacts from code, tests, and decisions | Initial formalization; gating completion claims | <!-- doc-ref-lint: ignore R4 arc-syncing-spec is an intentional test-pinned boundary reference to a future opt-in skill that does not ship today (plan §1.11) -->

`arc-syncing-spec` is not a shipped skill today. If and when it is added, it MUST ship as a separate opt-in workflow skill — never as language injected by the SessionStart bootstrap, the `arc-using` router, or any always-on instruction surface. The minimal-toolkit posture and harness/eval isolation depend on this boundary holding. <!-- doc-ref-lint: ignore R4 arc-syncing-spec is an intentional test-pinned boundary reference to a future opt-in skill that does not ship today (plan §1.11) -->
