code-agent

name	code-agent
description	Use when the task is mostly clear (50-90%) with one or two open decisions that can likely be resolved by inspecting the repo — not fully bounded, not a blank-slate design problem

Skill: code-agent

When

Task is mostly clear (50-90%) but 1-2 decisions remain open — resolvable by inspecting the repo.

Flow

flowchart TD
    A[Orient: arcs brief --lean --json] --> K[Knowledge: arcs knowledge search slug keywords]
    K --> B[Search: arcs search slug keywords]
    B --> C[Inspect repo — patterns, types, fixtures]
    C --> D{Confidence score >=80?}
    D -->|Yes| E[Implement — TDD for new behavior]
    D -->|No, inferable| E
    D -->|No, genuine ambiguity| F[Ask ONE targeted question]
    F --> E
    E --> G[Verify — affected tests + lint on changed files]
    G --> H{Complexity expanded?}
    H -->|No| I[Done]
    H -->|Yes| J[Pause — state issue — offer brainstorming]

Phase 0: Check Existing Knowledge

Before investigating or implementing, check what the DAG already knows:

arcs knowledge search <slug> "<task-keywords>" --lean --json

Look for:

• kind: pattern — existing conventions that apply to this change
• kind: gotcha — known traps in this area
• kind: lesson — prior learnings from similar work

If relevant entries exist, incorporate their guidance. Don't rediscover what's already known.

Capture Exit: Record What You Resolved

Phase 0 is read-only; close the loop on the way out. After implementing, if you resolved a non-obvious ambiguity or hit a gotcha worth saving, upsert it so the next agent doesn't re-investigate: arcs knowledge upsert <slug> "<title>" --kind=<pattern|gotcha> --summary="<what was resolved / the trap and how to avoid it>" --keywords="<k1,k2>" --source-files="<path,...>" --json. Skip when the work was mechanical and surfaced nothing non-obvious. Upsert is idempotent by title.

Behaviour

• Apply the-ladder during implementation — reach for stdlib / native / an installed dep before new code, and leave // SHORTCUT: markers for deliberate simplifications
• Inspect repo before asking anything
• Score self-confidence before any code edit; <80% triggers explore/web recovery, not improvisation
• Proceed on inferred defaults when repo makes it clear
• Ask at most one targeted question (product direction, naming, breaking trade-off)
• TDD for new non-trivial behavior; skip for structural changes covered by existing tests
• Lightweight bullet plan only when 3+ files and sequencing matters
• Verify scoped: lint + test only files you touched — NEVER the full suite. Pervasive change (shared types, config, build) or failures in out-of-scope files → report under BLOCKED_BY, never fix; full-project verification belongs to the devil-advocate completion gate

NOT for

• Fully bounded, no decisions → quick-dev
• Unclear/creative/design-shaping → brainstorming