Imported from karlorz/agent-skills (skills/dev-loop/skills/dev-loop/SKILL.md). Install upstream with npx skills add karlorz/agent-skills --skill dev-loop. Copyright stays with the author.

Dev Loop — PRD + Skillwiki (Generic Engine)

A single-pass dev cycle. When invoked, runs ONE cycle: refresh context, load project config, pick up the next claimable work item, drive it through the loop, exit. The PRD skill drives the work; skillwiki captures the knowledge in two tiers — project journal and global playbook. A pluggable interview phase (native 3-question default, optional grill-with-docs upgrade) sharpens requirements before SPEC. /dev-loop setup and /dev-loop setup-dev-loop provide interactive project bootstrap.

This skill is project-agnostic. All project specifics come from a config file in the active repo. If no config exists, the skill autodiscovers conventions or asks the user to bootstrap one.

Single-Pass Semantics

• One cycle per invocation. Do not iterate internally.
• Idempotent. If no claimable work exists and nothing is in progress, exit with a one-line status — do not invent work.
• Resumable. If a previous cycle left a work item mid-step, resume at the next unfinished step rather than restarting.
• Context management is harness-driven. Claude Code auto-fires /compact at the context limit; the dev-loop controller cannot invoke /compact or /clear (they are user-only slash commands). Do not assume programmatic context management is available.

Mode

Parse arguments for the keywords status, doctor, prep, investigate, ranked-audit, office-hours, setup, setup-dev-loop, config-lint, and dashboard (case-insensitive). doctor is an alias for status (operator-facing cycle preview). setup is an alias for setup-dev-loop (interactive project bootstrap). doctor is not the REFRESH doctor-worker dependency probe — status mode may read ~/.claude/dev-loop/last-doctor.json but does not spawn doctor-worker unless you explicitly run a full REFRESH core cycle.

If status or doctor is present, set MODE = status. Else if config-lint is present, set MODE = config-lint. Else if dashboard is present, set MODE = dashboard. Else if setup or setup-dev-loop is present, set MODE = setup. Else if ranked-audit is present, set MODE = ranked-audit. Else if office-hours is present, set MODE = office-hours. Else if prep is present, set MODE = prep. Else if investigate is present, set MODE = investigate. Otherwise set MODE = core (default).

Argument Parsing Order

1. Check for status or doctor keyword. If found, set MODE = status, remove from args. Remaining flags become STATUS_ARGS (e.g. --json, --preview-mode investigate, --orchestration goal).
2. Check for config-lint keyword. If found, set MODE = config-lint, remove from args.
3. Check for dashboard keyword. If found, set MODE = dashboard, remove from args. Remaining flags become DASHBOARD_ARGS (e.g. --refresh, --json).
4. Check for setup or setup-dev-loop keyword. If found, set MODE = setup, remove from args. Remaining args become SETUP_ARGS.
5. Check for ranked-audit keyword. If found, set MODE = ranked-audit, remove from args. Remaining flags become RANKED_AUDIT_ARGS.
6. Check for office-hours keyword. If found, set MODE = office-hours, remove from args. Remaining args become OFFICE_HOURS_ARGS.
7. Check for prep keyword. If found, set MODE = prep, remove from args. Remaining non-high args are preserved as PREP_ARGS.
8. Check for investigate keyword. If found, set MODE = investigate, remove from args.
9. Check for high keyword. If found, set INTENSITY = high, remove from args.
10. Remaining args → PREP_ARGS when MODE = prep; INVESTIGATE_TOPIC when MODE = investigate; STATUS_ARGS when MODE = status; CONFIG_LINT_ARGS when MODE = config-lint; DASHBOARD_ARGS when MODE = dashboard; SETUP_ARGS when MODE = setup; RANKED_AUDIT_ARGS when MODE = ranked-audit; OFFICE_HOURS_ARGS when MODE = office-hours.

Examples:

/dev-loop                                → MODE=core, INTENSITY=normal
/dev-loop high                           → MODE=core, INTENSITY=high
/dev-loop prep                           → MODE=prep, INTENSITY=normal
/dev-loop prep --limit 10                → MODE=prep, PREP_ARGS="--limit 10"
/dev-loop prep --lane work --work foo    → MODE=prep, PREP_ARGS="--lane work --work foo"
/dev-loop investigate                    → MODE=investigate, INTENSITY=normal
/dev-loop investigate high               → MODE=investigate, INTENSITY=high
/dev-loop investigate "plugin SDK"       → MODE=investigate, INTENSITY=normal, TOPIC="plugin SDK"
/dev-loop investigate high "plugin SDK"  → MODE=investigate, INTENSITY=high, TOPIC="plugin SDK"
/dev-loop status                         → MODE=status, INTENSITY=normal
/dev-loop status high                    → MODE=status, INTENSITY=high
/dev-loop doctor                         → MODE=status (alias)
/dev-loop status --json                  → MODE=status, STATUS_ARGS includes --json (JSON to stdout)
/dev-loop status --preview-mode investigate → MODE=status, preview investigate gates/blockers
/dev-loop ranked-audit --top 20           → MODE=ranked-audit, RANKED_AUDIT_ARGS="--top 20"
/dev-loop office-hours                    → MODE=office-hours
/dev-loop office-hours --all-projects     → MODE=office-hours, OFFICE_HOURS_ARGS="--all-projects"
/dev-loop office-hours "release triage"   → MODE=office-hours, OFFICE_HOURS_ARGS includes topic
/dev-loop setup                           → MODE=setup
/dev-loop setup-dev-loop                  → MODE=setup
/dev-loop config-lint                  → MODE=config-lint, INTENSITY=normal
/dev-loop config-lint --json           → MODE=config-lint, lint JSON to stdout
/dev-loop dashboard                    → MODE=dashboard, aggregate observability slices
/dev-loop dashboard --refresh          → MODE=dashboard, probe missing artifacts (read-only)
$dev-loop status                          → Codex preferred standard entrypoint
$dev-loop office-hours                    → Codex preferred standard entrypoint
$dev-loop setup                           → Codex preferred standard entrypoint

Mode Dispatch

After REFRESH (step 0), branch on MODE:

• dashboard → run Dashboard pipeline (read-only) below. Exit before WORK or writes.
• config-lint → run Config lint pipeline (read-only) below. Exit before WORK or any write cycle steps. Validates .claude/dev-loop.config.md against documented template rules via scripts/dev-loop-config-lint.js.
• status → run the Status pipeline (read-only) below. Exit before WORK, SPEC, PLAN, EXECUTE, REVIEW, MERGE, SAVE, RETRO, PUSH, DEPLOY, or any vault/work-item writes. Do not spawn doctor-worker for status unless REFRESH subset explicitly includes it; prefer reading last-doctor.json and inline dependency probes via scripts/dev-loop-status.js.
• core → run The Loop (steps 1–14) or IDLE DISCOVERY as documented below.
• setup → run the setup pipeline from setup-dev-loop/SKILL.md. Use this mode for both /dev-loop setup and /dev-loop setup-dev-loop.
• ranked-audit → run the unattended read-only ranked lifecycle scan from ranked-audit/SKILL.md. It may publish one managed evidence report, but it does not change work-item lifecycle state.
• office-hours → run the attended office-hours pipeline from office-hours/SKILL.md. It writes the requirements report described there and does not set preflight readiness.
• prep → gate on query_vault in BACKEND_CAPS. If absent, refuse: "Prep mode requires a vault — run /dev-loop setup to configure one." If present and PREFLIGHT_POLICY.enabled != false, run the Preflight Prep Pipeline below. If disabled, refuse with the config path to update.
• investigate → gate on query_vault in BACKEND_CAPS. If absent, refuse: "Investigate mode requires a vault — run /dev-loop setup to configure one." If present, run the investigate pipeline from investigate/SKILL.md. The investigate companion shares REFRESH state (BACKEND_CAPS, VAULT_TYPES, DEP_DRIFT, CRITICAL_PATHS, config) — do not re-derive.

Investigate Pipeline (summary)

┌─────────────────────────────────────────────────────────┐
│ INVESTIGATE (when MODE = investigate)                    │
│  1. QUERY     Existing work items + retros for dedup    │
│  2. SCAN      Research-worker (code + vault + transcripts)│
│  3. DEEPEN    Deep-research (high or user topic only)   │
│  4. TRIAGE    Deduplicate, rank, apply intensity cap    │
│  5. SPEC      Queue findings (schema-adaptive output)   │
│  6. RETRO     Log investigation results                 │
│  7. SAVE      Vault auto-commit                         │
└─────────────────────────────────────────────────────────┘

See investigate/SKILL.md for full step details. Key properties:

• Output: queued findings; use status: proposed only when the local schema validates it, otherwise use raw transcript captures. Current SkillWiki schemas such as 0.9.16 reject status: proposed, so those vaults use raw captures. Humans promote findings to planned before CORE executes them.
• Tiered: concrete findings → full spec, exploratory → stub
• Dedup: slug-based + status-aware + archive check
• Cap: max_items (normal) or max_items * 2 (high). Default 5/10.
• Vault required (ADR: investigate-mode-vault-required)

Status pipeline (read-only, when MODE = status)

Operator observability: what the next write cycle would do, without executing it.

┌─────────────────────────────────────────────────────────┐
│ STATUS (when MODE = status or doctor alias)              │
│  S0. REFRESH (read-only subset)  Config, caps, vault     │
│       resolution; optional skill-cache drift check.      │
│       Do NOT reload-plugins, commit, push, or write      │
│       vault/work items.                                  │
│  S1. PROBE   node scripts/dev-loop-status.js             │
│  S2. REPORT  Markdown + JSON under                       │
│       .claude/dev-loop/status/ (gitignored session out)  │
│  S3. EXIT    One-line summary; never enter WORK/EXECUTE   │
└─────────────────────────────────────────────────────────┘

S0. REFRESH subset: Load ./.claude/dev-loop.config.md, derive BACKEND_CAPS, PRD_CAPS, ORCHESTRATION_CAPS (heuristic only — do not require active /goal), PREFLIGHT_POLICY, CI_DISCOVERY, RELEASE_POLICY preview fields, and vault path (knowledge_backends.skillwiki.vault or legacy vault). Re-read CLAUDE.md only if needed for fallback slug detection. Skip: plugin reload, ad-hoc capture mutation, doctor-worker spawn (read ~/.claude/dev-loop/last-doctor.json instead), vault auto-commit, skillwiki doctor network writes.

S1. PROBE: From the skill directory (or repo root), run:

node skills/dev-loop/scripts/dev-loop-status.js \
  --repo <cwd> \
  --project <slug> \
  --host <codex|claude|unknown> \
  --format both \
  --intensity <normal|high> \
  --preview-mode <core|prep|investigate|status> \
  --orchestration <attended|goal>

Resolve --host from the live platform capability; do not infer the active cache from whichever filesystem entry is newest. STATUS_ARGS may pass --no-write (stdout only), --format json|markdown, or --vault <path> override. Map user --json to --format json --no-write when appropriate.

Optional Codex/Agent isolation: Agent(subagent_type: "dev-loop:status-worker", model: "sonnet", ...) per agents/status-worker.md (inline node fallback when dispatch unavailable).

S2. REPORT: Helper writes dev-loop-status.v1 JSON and human Markdown per templates/status-report.md (sections in PRD). Reports expose independent health (state, structured reasons, observed and relevant dependency gaps) and lifecycle (state, next_action, reason) objects. Optional dependency gaps degrade health only when their declared capability participates in the configured preview operation. overall remains a compatibility projection of those objects. Treat a configured, unresolved vault as degraded for skillwiki projects, not fatal, unless preview-mode is prep or investigate; knowledge_layer: none is not itself a health failure.

Read-only deny-list (hard rule): status mode must not create work items, edit spec/plan, append retros, git commit, git push, gh pr create, deploy, run bump_script, tag, skillwiki archive, or SAVE/MERGE vault push. Inventory and status probes are read-only subprocesses.

S3. EXIT: Emit Status: <healthy|degraded|blocked> — next <action> — reports at <paths>. Exit code 1 when overall.state === blocked (optional for automation).

Companion detail: status/SKILL.md. HUD one-liner: scripts/dev-loop-status-hud.js (reads newest *-status.json; optional --probe).

Config lint pipeline (read-only, when MODE = config-lint)

Validates the project config file against template-documented rules before a write cycle or /goal batch.

┌─────────────────────────────────────────────────────────┐
│ CONFIG-LINT (when MODE = config-lint)                    │
│  L0. REFRESH (read-only subset)  Load config path only   │
│  L1. LINT    node scripts/dev-loop-config-lint.js        │
│  L2. REPORT  .claude/dev-loop/lint/*.{md,json}           │
│  L3. EXIT    No WORK, vault, git, PR, or release writes  │
└─────────────────────────────────────────────────────────┘

L1. LINT:

node skills/dev-loop/scripts/dev-loop-config-lint.js \
  --repo <cwd> \
  --format both

Map user --json to --format json --no-write. Output schema: dev-loop-config-lint.v1. Checks include: required slug / release_branch, valid prd_layer / prd_pipeline / knowledge_layer, vault when skillwiki, ci_discovery + required_checks, preflight lanes/limit, merge_policy strategy/method + per-work-item approval safety, release_policy.auto_bump + trigger_globs + bump_script existence, publish_via runtime-truth verification (tag trigger in .github/workflows/ when ci-tag-trigger), e2e_scripts paths on disk, legacy vault: alias advisory.

Why-skipped (read-only): node skills/dev-loop/scripts/dev-loop-why-skipped.js --project <slug> --work <work-folder> — missing automation gates + inventory findings for one item.

Config migrate (read-only): node skills/dev-loop/scripts/dev-loop-config-migrate.js --repo <cwd> — compares legacy top-level vault: to knowledge_backends.skillwiki.vault; suggests YAML fragments (dev-loop-config-migrate.v1). Reports under .claude/dev-loop/migrate/ unless --no-write.

Write preflight (read-only): node skills/dev-loop/scripts/dev-loop-write-preflight.js --repo <cwd> --intent commit|push|write [--landing-route <route>] [--from-branch <name>] — deterministic git common-dir/worktree identity, branch, detached HEAD, submodule state, and task-sandbox ownership. Exit 0 only when the intended mutation is allowed; refuses release-branch commits/pushes when repository policy forbids them (dev-loop-write-preflight.v1).

Verification + dispatch (read-only): node skills/dev-loop/scripts/dev-loop-verification-dispatch.js --repo <cwd> — typed verification commands vs scripts (with timeouts) and capability-driven spawn/wait/cleanup/model/isolation plans. Non-Claude platforms must not require Claude-only tools (dev-loop-verification-dispatch.v1).

Operator dashboard (read-only): node skills/dev-loop/scripts/dev-loop-dashboard.js --repo <cwd> — aggregates newest status, config-lint, migrate artifacts plus ~/.claude/dev-loop/last-doctor.json (dev-loop-dashboard.v1). Optional --refresh runs missing probes with --no-write. Reports under .claude/dev-loop/dashboard/ unless --no-write.

Read-only deny-list: same as status mode — no implementation or vault mutations.

Dashboard pipeline (read-only, when MODE = dashboard)

Aggregates newest local observability artifacts (status, lint, migrate, doctor HUD).

┌─────────────────────────────────────────────────────────┐
│ DASHBOARD (when MODE = dashboard)                        │
│  D0. REFRESH (read-only subset)  Config path only        │
│  D1. AGG     node scripts/dev-loop-dashboard.js          │
│  D2. REPORT  .claude/dev-loop/dashboard/*.{md,json}      │
│  D3. EXIT    No WORK, vault, git, PR, or release writes  │
└─────────────────────────────────────────────────────────┘

node skills/dev-loop/scripts/dev-loop-dashboard.js \
  --repo <cwd> \
  --format both \
  --project <slug>

Map --json to --format json --no-write. Pass --refresh when DASHBOARD_ARGS includes it. Optional --project for refresh probes.

Preflight Prep Pipeline

/dev-loop prep is a human-attended pre-implementation workflow. It discovers current project work, dry-runs what an autonomous cycle would try to pick up, batches all human questions, and writes readiness state only after explicit approval. It never implements code and never starts /goal.

┌─────────────────────────────────────────────────────────┐
│ PREFLIGHT PREP (when MODE = prep)                        │
│  P0. REFRESH    Load config and PREFLIGHT_POLICY          │
│  P1. INVENTORY  scripts/preflight-inventory.js            │
│  P2. VERIFY     Cross-check selected items on disk/git    │
│  P3. QUESTIONS  Build one batch manifest + defaults       │
│  P4. APPROVE    AskUserQuestion in main session           │
│  P5. WRITE      Approved metadata/managed sections only   │
│  P6. VALIDATE   skillwiki validate touched specs/plans    │
│  P7. REPORT     projects/{slug}/requirements/ report      │
│  P8. SUGGEST    Suggested /goal text; do not start it     │
└─────────────────────────────────────────────────────────┘

P0. REFRESH config. Reuse normal REFRESH state. Require query_vault in BACKEND_CAPS. Resolve preflight config into PREFLIGHT_POLICY with defaults:

• enabled: true
• default_limit: 5
• default_lanes: [work, captures, hygiene]
• require_approved_spec_and_plan: true
• unattended_not_ready_behavior: skip
• defaults: {}

P1. INVENTORY. Run the deterministic helper from the skill directory:

node scripts/preflight-inventory.js \
  --project <slug> \
  --vault <vault> \
  --repo <cwd> \
  <PREP_ARGS or defaults from PREFLIGHT_POLICY>

Supported prep args: --limit <n>, --all, --lane <work|captures|hygiene> (repeatable or comma-separated), and --work <slug>. Default to a small prioritized batch. The helper returns three lanes:

• work: active work items (planned, in-progress) plus repairable legacy proposed/schema issues.
• captures: unclaimed executable raw transcripts (kind: task|bug).
• hygiene: structural/staleness findings such as missing spec/plan or unsupported status values.

P2. VERIFY selected candidates. Before asking or writing, verify every selected candidate against current disk and git state:

• Re-read the selected spec.md/plan.md or raw transcript path.
• Compare the current sha256 to inventory output; if changed, mark the item stale and exclude it from writes until re-inventoried.
• Re-run skillwiki validate on selected specs/plans.
• Re-check lightweight git history matches surfaced by inventory to avoid preparing work that has already shipped.

P3. SYNTHESIZE question manifest. Build one batch manifest, grouped by candidate, with recommended defaults first. Include:

• Scope, acceptance, compatibility, and execution-risk questions that would otherwise interrupt SPEC/PLAN/EXECUTE.
• Any repair actions required for legacy proposed, in_progress, missing spec/plan, missing status, or stale git evidence.
• Explicit actions per candidate: approve, override, or defer.
• Project-level defaults from PREFLIGHT_POLICY.defaults, clearly labelled as recommendations. Promote new stable answers into config only after separate explicit approval.

P4. ASK batch approval. Ask in the main session only. Do not spawn a subagent for approval; AskUserQuestion is interactive and must remain in the parent session. One approval can cover the whole manifest, but partial approval is first-class: approved candidates proceed to P5, deferred candidates keep or receive preflight_state: needs_human|deferred.

P5. WRITE approved readiness state. No writes are allowed before P4 approval. After approval, write only selected approved items and only:

• Managed frontmatter fields: automation_ready, human_questions_resolved, spec_preflight_approved, plan_preflight_approved, preflight_state, last_preflight, and merge_auto_approved. General approval does not imply merge approval: default merge_auto_approved: false and set it true only when the operator explicitly approves auto-merge for that candidate.
• Managed body sections: ## Preflight Approval, ## Automation Readiness, and ## Open Questions.
• Spec/plan refinements that directly encode approved execution-critical answers. Batch-level summaries belong under projects/{slug}/requirements/, not inside every work item.

Use a vault lock when VAULT_SYNC_PEER_AWARE is true. Re-read and hash each target immediately before writing; if the hash differs from P2, skip that target and report it as stale. Preserve unrelated frontmatter/body content.

P6. VALIDATE touched specs/plans. Run skillwiki validate for every touched spec.md and plan.md. If validation fails, repair only the managed edits when the fix is obvious; otherwise leave the item not-ready and report the blocker. Do not mark an invalid item executable.

P7. REPORT. Write a batch report under: projects/{slug}/requirements/YYYY-MM-DD-dev-loop-preflight-prep.md. Include inventory scope, approved items, deferred items, questions answered, defaults used, validation results, stale/hash conflicts, and remaining automation readiness skips. This report is the project-level audit trail.

P8. SUGGEST /goal. Emit a suggested /goal command for the approved ready batch, for example:

/goal "Run /dev-loop until all automation-ready planned work for project <slug> is completed, tests pass, and the vault is clean."

Do not start /goal; the user owns that lifecycle.

Write safety contract: inventory and validation are deterministic tooling; synthesis and approval are prompt-driven. The preflight write phase must satisfy all of these gates: explicit approval, selected items only, managed frontmatter whitelist, managed body sections, hash check, vault lock when available, and validation after write.

Intensity Level

Parse arguments for the keyword high (case-insensitive). If present, set intensity = high; otherwise intensity = normal.

Intensity applies to BOTH modes — core and investigate use the same variable.

normal (default)

Respect priority tiers. Pick up P2+ items; only fall through to P3 when nothing higher exists. Use idle fast-path when truly idle.

high

Aggressive mode — ignore priority gates entirely. Every finding is claimable work regardless of P-score. Specifically:

• WORK step: pick the top-ranked item from the backlog without checking its priority tier. P3 and P4+ items are treated the same as P0.
• IDLE DISCOVERY step 5: remove the "only P3 if no P2+" guard. Execute the top research recommendation unconditionally.
• Trivial fast-path: prefer it more aggressively — anything under ~80 LOC qualifies (raised from ~50).
• Research trigger: after idle maintenance, always invoke the research agent with high mode.
• P3+ pickup: in high mode there is no such thing as "only P3 left" — all items are equal. Do NOT exit idle when the backlog has any items.

Model Strategy

Dev-loop spawns agents for implementation, code review, research, and knowledge maintenance. To balance cost and quality, each agent-eligible step uses the model tier matched to its complexity. Planning and decision agents inherit the invoking parent model. Research and mechanical maintenance remain on Sonnet:

The mechanical maintenance agents wiki-lint, wiki-audit, wiki-crystallize, and proj-distill remain on sonnet; proj-decide inherits the parent model because ADRs require architectural judgment.

Steps that stay inline (not agent-eligible): WORK, MERGE (commit + push + PR creation only), SAVE, DISTILL, AUDIT, VERIFY, RETRO, E2E, DEPLOY, PUSH — these are CLI commands, file writes, or skill invocations with low token volume. MERGE's CI health gate spawns ci-health-worker (sonnet). IDLE mechanical maintenance skills (lint, audit, crystallize, distill) are agent-eligible and run on sonnet; proj-decide is agent-eligible and inherits the invoking parent model.

Cost impact: ~80% of agent-eligible work (EXECUTE subagents + SIMPLIFY + MERGE CI gate + research + mechanical maintenance) runs on Sonnet. SPEC, PLAN, and architectural decision work inherit the parent model's capability.

Interview Capability Matrix

Interview capabilities are separate from knowledge backends — they are interactive, session-scoped, and declared in the interview config section. When the interview section is absent, both capabilities are off and the loop runs fully automated.

Interview backends are resolved at REFRESH:

1. Parse interview section from config. If absent → both capabilities off.
2. setup_interview: always available via bundled setup-dev-loop skill. If grill-with-docs is installed, the glossary section delegates to it.
3. work_item_interview: resolves to native by default. If upgrade is set (e.g., grill-with-docs) AND the skill is installed at ~/.claude/skills/<name>/SKILL.md, the upgrade overrides native.
4. trigger field: auto (ambiguity detection), manual (only on grill: true), or never (fully automated).

Key constraint: AskUserQuestion is confirmed broken in subagents (Claude Code GitHub issues #34592, #12890). All interview logic MUST run in the main session. This matches dev-loop's existing architecture — SPEC and PLAN already run in the parent session; EXECUTE dispatches sonnet subagents which don't need interactive tools.

Interview Engine (Native Default)

When work_item_interview resolves to native, the GRILL step runs three fixed AskUserQuestion calls in the main session:

1. Scope: "What's the scope of this change? What's explicitly out of scope?" Options: ["Feature + tests", "Bug fix only", "Refactor (no behavior change)", "Other"]
2. Constraints: "What constraints exist? (existing code to respect, performance requirements, compatibility concerns)" Options: ["None specific", "Must match existing patterns", "Performance-critical path", "Other"]
3. Acceptance: "How do you know it's done? What must be true?" Options: ["Tests pass + manual verification", "Tests pass only", "Code review approval", "Other"]

Output: a Q&A summary appended as a preamble to spec.md in the work item:

## Interview Summary (native)

- **Scope**: Feature + tests — adding X with full test coverage
- **Constraints**: Must match existing patterns in <file>
- **Acceptance**: Tests pass + manual verification

This preamble feeds into the SPEC step — the PRD skill reads it as context before writing the full spec. When grill-with-docs or grill-me is the backend, their output (sharpened terminology, resolved decisions) serves the same role.

Model Strategy (continued)

CLAUDE_CODE_SUBAGENT_MODEL: This env var acts as a global override — when set to a model ID, it forces ALL subagents to that model regardless of per-agent model parameters.

For dev-loop's tiered model strategy to work correctly, CLAUDE_CODE_SUBAGENT_MODEL MUST be unset or empty ("").

If this var is set (e.g., to claude-sonnet-4-6), every subagent from every skill will run on that model, and per-agent overrides are silently ignored.

The current settings.json at ~/.claude/settings.json has "CLAUDE_CODE_SUBAGENT_MODEL": "" — this is correct and should stay empty for per-agent model control to function.

System Context

The knowledge layer is pluggable via knowledge_layer in the project config. Steps branch on capabilities, not backend names — check if <capability> in BACKEND_CAPS rather than if knowledge_layer == "skillwiki". This lets new backends slot in by declaring which capabilities they provide.

The Workflow Profile Resolver runs before PRD capability resolution. It picks the orchestration profile; the PRD layer then supplies optional capabilities inside that profile. Installation proves availability, never activation. Steps 3–6 branch on PRD_CAPS instead of naming specific skills. Pipeline templates (prd_pipeline) control which steps run; PRD_CAPS controls which skill to invoke per step. Profile, pipeline, and provider are separate concerns.

Workflow Profile Resolver

Profiles:

Selection modes are adaptive and fixed. fixed requires an explicit workflow_profile. adaptive selects guided only when capability evidence is needs-guidance or risk is elevated; otherwise it selects native. Adaptive selection never chooses full.

Resolve authority in this order:

1. current user instruction
2. work-item declaration
3. project configuration
4. legacy explicit prd_pipeline mapping
5. user-level default
6. built-in adaptive default

Legacy mappings are full → full, tdd-first → guided, and single-pass / debug-only / manual → native. Invalid policy is unresolved and blocks the write cycle; it never falls through to full. Goal, headless, CI, and satellite sessions never prompt. The resolver reports its authority and reason so status output remains explainable.

Capability Matrix

At REFRESH, BACKEND_CAPS is resolved: read knowledge_layer from config, look up the backend in knowledge_backends (or derive defaults), and store the set of capabilities this backend provides. Steps then check membership in BACKEND_CAPS instead of testing the backend name directly.

See config template for knowledge_backends registry details.

PRD Capability Matrix

At REFRESH, resolve the workflow profile first. Then resolve PRD_CAPS alongside BACKEND_CAPS: read prd_layer from config (default: manual), look up the backend in prd_backends (or derive defaults), and store the set of PRD capabilities + registered skill names. Installed skills only prove availability. Steps 3–6 check PRD_CAPS membership instead of naming specific skills.

Orchestration Capability Set (v1.22.0)

ORCHESTRATION_CAPS is resolved at REFRESH, orthogonal to both BACKEND_CAPS and PRD_CAPS. It contains only positive capabilities and detects whether the current session is running inside a platform-provided autonomous loop (/goal).

Detection is heuristic, not API-based — no platform (Claude Code, Codex, Antigravity) exposes a programmatic /goal detection mechanism (verified May 2026). The heuristic checks:

1. System prompt or recent messages mention an active goal, completion condition, or evaluator in a /goal-specific context.
2. The conversation contains evaluator feedback strings ("condition not yet met", "continue working", "goal active").
3. The session was invoked with a /goal command visible in the transcript.

Avoid false positives: do not set goal_context for generic uses of the word "goal", design discussions about /goal, or user requests to prepare a future /goal. Require an active-loop signal, not merely documentation text.

When goal_context is true:

• Add goal_context and multi_cycle_orchestrator to ORCHESTRATION_CAPS.
• Add non_interactive_goal unless interview.work_item.goal_override: allow explicitly permits monitored interaction.
• Set GRILL_TRIGGER_OVERRIDE = never when non_interactive_goal is present.
• Log: "Goal context detected — interactive prompts suppressed for this cycle."
• Emit: "Running under /goal — dev-loop will complete one work item per turn. The /goal evaluator handles multi-cycle continuation."

When goal_context is false (default): no behavior change. All existing workflows continue unchanged.

Steps that need interactive input check for non_interactive_goal before calling AskUserQuestion. If present, use the documented fallback (skip, or use config defaults).

Automation readiness gate (unattended contexts): When non_interactive_goal is present, CORE must only select work items that are explicitly marked ready for unattended execution. Required frontmatter:

automation_ready: true
human_questions_resolved: true
spec_preflight_approved: true
plan_preflight_approved: true
preflight_state: ready

Work items missing any field, or carrying any false/non-ready value, are not claimable in unattended mode. Skip them, continue scanning for ready work, and emit an Automation Readiness Skips summary with item slugs and missing fields. Do not stop the cycle just because not-ready work exists. The configured PREFLIGHT_POLICY.unattended_not_ready_behavior defaults to skip; any future behavior must remain non-interactive under /goal.

Platform Dispatch Capability (v1.24.8)

PLATFORM_DISPATCH is an instruction-level dispatch rule resolved by the agent at REFRESH alongside ORCHESTRATION_CAPS. It probes the model-visible tool surface and records which dispatch syntax the agent must use for later worker call sites. This is not compiled dispatcher code; it is a required prompt contract for the agent following this skill.

Detection (run once at REFRESH):

1. Probe available tools in the current session:
   • If Agent tool exists → DISPATCH_MODE = claude_code
   • Else if spawn_agent tool exists → DISPATCH_MODE = codex
   • Else → DISPATCH_MODE = inline_only
2. Store DISPATCH_MODE for all subsequent worker spawns.

Dispatch rules per mode:

Every Agent(...) call site in this skill implies the Codex equivalent. When DISPATCH_MODE = codex, translate each Agent(...) pseudo-call to spawn_agent + wait_agent + close_agent. The Claude subagent_type value does not become Codex agent_name; use it to choose a stable task_name and to include the worker instructions in the prompt. For example, subagent_type: "dev-loop:doctor-worker" becomes a child task named doctor-worker whose prompt tells the child to follow the dev-loop doctor-worker contract. See references/codex-tools.md for the full tool mapping table and Codex App sandbox-finishing contract.

Inline fallback applies uniformly: If any dispatch (Claude or Codex) fails at spawn time — tool error, multi_agent disabled, balance error, unknown agent — fall back to inline Skill(…) execution. The existing DEP_DRIFT / inline-fallback machinery handles this identically regardless of DISPATCH_MODE.

Pipeline Templates

Pipeline templates control which steps run. PRD_CAPS controls which skill to invoke per step. These are two separate concerns.

Default pipeline per resolved workflow profile:

• native → single-pass
• guided → tdd-first
• full → full

An explicit prd_pipeline remains a separate stage-template override. In legacy configs without workflow fields, it also maps through the resolver as documented above. Provider choice never changes the selected profile.

Cross-Cutting Disciplines

Cross-cutting concerns (TDD, debugging) are advisory overlays, not pipeline stages. They are declared in prd_disciplines config with when and mode:

prd_disciplines:
  - skill: superpowers:test-driven-development
    when: execute       # apply during EXECUTE step
    mode: advisory      # the execute skill decides how to use it
  - skill: superpowers:systematic-debugging
    when: failure       # invoke when EXECUTE encounters errors
    mode: reactive      # interrupt EXECUTE, invoke debugging, resume

when values: execute, review, failure, always mode values: advisory (skill decides), mandatory (hard gate), reactive (interrupt on trigger)

Knowledge Tiers

The Loop (Single Pass)

┌─────────────────────────────────────────────────────────────┐
│ PRELUDE (mandatory)                                         │
│  0. REFRESH   Reload plugins + load project config          │
│               + read CLAUDE.md + MEMORY.md                  │
├─────────────────────────────────────────────────────────────┤
│ CORE (mandatory)                                            │
│  1. QUERY     wiki-query → vault context check              │
│  2. WORK      proj-work  → create work item + redirect paths│
│  2b. GRILL    <Interview backend> → sharpen requirements    │
│  3. SPEC      <PRD skill> → spec.md at vault path           │
│  4. PLAN      <PRD skill> → plan.md at vault path           │
│  5. EXECUTE   isolate (using-git-worktrees / .worktrees)    │
│               → sdd-execute-worker in worktree cwd          │
│  6. REVIEW    simplify-worker or Skill(simplify:simplify)  │
│               → fix findings                              │
│  6b. MERGE    PR from feature branch → main (if branch ≠   │
│               release_branch and code was committed)        │
├─────────────────────────────────────────────────────────────┤
│ OPTIONAL (run if config declares)                           │
│  7. SAVE      wiki-crystallize → session insights           │
│  8. E2E       project test suites → all must exit 0         │
│  9. DEPLOY    deploy artifacts to remote hosts (if any)     │
│ 10. PUSH      release per project config (CI publishes)     │
├─────────────────────────────────────────────────────────────┤
│ POSTLUDE — single-cycle (mandatory)                         │
│ 11. RETRO     append retro to log + auto-capture findings   │
├─────────────────────────────────────────────────────────────┤
│ POSTLUDE — every-3-cycles consolidation (conditional)       │
│ 12. DISTILL   proj-distill (concepts) / proj-decide (ADRs)  │
│ 13. AUDIT     claude-md-improver → CLAUDE.md updates        │
│ 14. VERIFY    audit_vault cap → provenance integrity       │
├─────────────────────────────────────────────────────────────┤
│ IDLE DISCOVERY (when CORE finds no claimable work)          │
│  Skip to POSTLUDE steps 11–14 regardless of cadence.        │
│  Then run maintenance based on BACKEND_CAPS:               │
│  - lint_vault cap: wiki-lint/audit/crystallize/distill     │
│  - no lint_vault: git gc, prune branches, project lint     │
│  Then invoke research agent (see research/SKILL.md).      │
│  Exit with one-line summary of what was done.               │
└─────────────────────────────────────────────────────────────┘

Step Details

0. REFRESH — context hygiene + config load (mandatory, ~15s)

1. Immutable plugin drift guard — before any other step, diagnose the active host's exact declared plugin version:

   • Read the version from both dev-loop plugin manifests and require them to agree.
   • Resolve the runtime host from the live platform capability (DISPATCH_MODE = codex|claude_code) or pass an explicit host to dev-loop-status.js --host <codex|claude>. Unknown hosts fail closed.
   • For Codex, inspect only ~/.codex/plugins/cache/karlorz-agent-skills/dev-loop/<version>/. For Claude, inspect only ~/.claude/plugins/cache/karlorz-agent-skills/dev-loop/<version>/. For Grok, inspect only ~/.grok/installed-plugins/dev-loop-<hash>/.
   • Hash the source and exact-version cached SKILL.md. Other semantic versions may be listed as inactive evidence, but never selected by mtime.
   • States:
     • in_sync: exact declared version exists and hashes match → proceed.
     • not_installed: no active-host cache is installed → block.
     • installed_version_stale: only another version is installed → block.
     • drifted_stale: exact version exists but its payload hash differs → block; same-version cache mutation is not a valid repair.
     • unknown_host or manifest_version_mismatch → block without suggesting a write.
   • Codex recovery: advance the plugin version if the declared version is already released and its source payload changed, then run codex plugin add dev-loop@karlorz-agent-skills --json, verify the returned version/path and source/cache hashes, stop the stale current session, then start a new Codex chat or CLI session.
   • Claude recovery: advance the plugin version if the declared version is already released and its source payload changed, then run claude plugin update dev-loop@karlorz-agent-skills, verify hashes, then restart Claude Code as required by the updater.
   • Never copy into an existing versioned cache, delete session history, or present a Claude refresh command as Codex remediation.

2. Respect the session loading boundary — installing or updating a plugin does not hot-swap instructions already loaded into the current agent session. After recovery, end the stale session and verify the next cycle from a fresh session before allowing writes.

3. Load project config in this order:

   • Primary: read ./.claude/dev-loop.config.md (relative to CWD). Invoke scripts/dev-loop-config-schema.js, which runs the bounded, read-only Python/PyYAML bridge in dev-loop-config-schema.py. Consume its normalized nested config, path/line provenance, block metadata, and diagnostics. YAML maps deep-merge across fenced blocks; later scalars and lists replace earlier values. Initial Markdown frontmatter is metadata, while key-shaped YAML outside a yaml/yml fence is an error. Malformed YAML, duplicate keys, unknown schema keys, invalid nested types, parser timeout, or missing Python/PyYAML block the write cycle. Never fall back to regex config parsing. The schema is documented in templates/project-config.md. Parse knowledge_layer (default: skillwiki). Then resolve BACKEND_CAPS — read the knowledge_backends map if present in config (see templates/project-config.md for schema); otherwise derive defaults from knowledge_layer plus the legacy top-level vault alias when present. SkillWiki vault resolution: canonical vault config lives at knowledge_backends.skillwiki.vault; legacy top-level vault is still supported as an alias for older configs. If the configured SkillWiki vault is auto or absent, run skillwiki path. If that succeeds, store the returned path as vault and enable SkillWiki BACKEND_CAPS. If skillwiki path fails, use a validated ~/wiki fallback only when ~/wiki/SCHEMA.md and ~/wiki/projects/ both exist; this is the validated ~/wiki fallback. Emit "vault: auto could not resolve via skillwiki path. Using validated fallback ~/wiki." If neither resolves, disable vault-backed capabilities for this cycle and warn "vault: auto could not resolve a SkillWiki vault. Vault-backed steps are disabled for this cycle. Configure skillwiki path or set an explicit vault path." Explicit non-auto paths remain supported as intentional overrides. When an explicit path disagrees with skillwiki path, keep the explicit path but warn: "Configured SkillWiki vault '' differs from skillwiki path ''. Use vault: auto for portable configs, or keep the explicit path only if this repo is intentionally pinned to one machine." Resolve workflow profile before providers. Use scripts/dev-loop-workflow-profile.js as the shared resolver. Assemble authorities from the current user instruction, selected work-item declaration, project workflow_selection / workflow_profile / workflow_capability / workflow_risk, user-level defaults, and the built-in adaptive default. Preserve that precedence. Explicit legacy prd_pipeline maps only after current user, work-item, and project workflow policy. Store the result as WORKFLOW_PROFILE, including mode, authority, reason, default pipeline, and unresolved diagnostics. The resolver never prompts and adaptive selection never chooses full. If unresolved, block the write cycle with workflow_profile_unresolved. Then resolve PRD_CAPS — read prd_layer from config, defaulting to manual. Read prd_backends if present; otherwise derive defaults from the selected provider. Probe installed skills only to determine whether a configured capability is available. Installation proves availability, never activation. Store the capabilities and registered skill names as PRD_CAPS. Resolve prd_pipeline from an explicit configured override, otherwise from WORKFLOW_PROFILE.defaultPipeline; store it as PRD_PIPELINE. Resolve prd_disciplines if declared: parse include_paths and exclude_paths on each discipline entry (both are optional — omit for global scope). Warn if a discipline has mode: mandatory without include_paths: " is mandatory globally — consider scoping with include_paths." This is a warning, not an error — the discipline still runs. Backwards compat: omitted include_paths = matches all changed files (current behavior). Store disciplines in priority order as PRD_DISCIPLINES. Resolve interview backends — parse the interview section from config. If absent → setup_interview and work_item_interview both absent from BACKEND_CAPS (loop runs fully automated). If present:

     • Parse interview.setup — setup_interview ∈ BACKEND_CAPS. Backend: setup-dev-loop (bundled). If glossary: grill-with-docs is set AND ~/.claude/skills/grill-with-docs/SKILL.md exists, delegates glossary section to it.
     • Parse interview.work_item — work_item_interview ∈ BACKEND_CAPS. Resolve backend: check if upgrade is set AND installed at ~/.claude/skills/<upgrade>/SKILL.md — if yes, backend = upgrade skill name; otherwise backend = native. Store as INTERVIEW_BACKEND.
     • Parse interview.work_item.trigger — store as INTERVIEW_TRIGGER (auto, manual, or never).
     • Parse interview.work_item.goal_override — store as INTERVIEW_GOAL_OVERRIDE (never or allow, default never). Resolve ORCHESTRATION_CAPS — inspect the current system context and recent transcript for active /goal-loop signals (see Orchestration Capability Set). If strong evidence is present, add goal_context and multi_cycle_orchestrator. Add non_interactive_goal unless INTERVIEW_GOAL_OVERRIDE == allow. Do not set any goal capability for generic mentions of "goal" or for discussions about setting a future /goal. Resolve CI discovery — parse ci_configured and ci_discovery from config. If ci_configured: true:
     • ci_discovery: runtime (default) → store CI_DISCOVERY = runtime, REQUIRED_CHECKS = [] (discovered at MERGE time via API).
     • ci_discovery: explicit → store CI_DISCOVERY = explicit, REQUIRED_CHECKS = required_checks list from config. If ci_configured: false or absent → CI_DISCOVERY = none, REQUIRED_CHECKS = []. Resolve merge authority separately — parse merge_policy with fail-closed defaults: {strategy: repo-policy, auto_merge: false, allow_local_merge: false, merge_method: squash, require_work_item_approval: true}. Store the normalized result as MERGE_POLICY independently of CI_DISCOVERY; CI existence or health never grants merge authority. strategy is repo-policy (branch-policy compatibility alias) or pull-request; merge_method is squash, merge, or rebase. auto_merge: true requires require_work_item_approval: true, and the active work-item spec must carry merge_auto_approved: true before the runtime gate may enable auto-merge. Resolve WORKTREE_POLICY — parse worktree_policy.enabled (default true when absent or when the block is absent). Store {enabled}. Shared helper: skills/dev-loop/scripts/dev-loop-isolation-landing.js (parseWorktreePolicy, parseMergePolicy). Do not run the helper as a required shell step; agents may use the same defaults if they parse YAML themselves. Resolve critical_paths — parse into CRITICAL_PATHS dict (name → {code, vault, history_pins}). Absent or empty → {} (equal priority). Schema: see templates/project-config.md § Critical paths. Setup flow: setup-dev-loop/SKILL.md Section G. Resolve fact_check — parse into FACT_CHECK_CAPS (source_order, web_available bool after validating web_tools.primary against installed MCP tools, evidence_contract). Absent or enabled: false → {}. Pass to SPEC/PLAN steps. Schema: templates/project-config.md § Fact-check tier. Setup flow: setup-dev-loop/SKILL.md Section H. Resolve code_review — parse the code_review block (since v1.15.0). Build CODE_REVIEW_BACKENDS session list (order: always-on backends first, optional backends appended per intensity gate):
     • Always include simplify:simplify (base backend). Prefer running it through dev-loop:simplify-worker for subagent isolation when the platform supports worker dispatch; fall back to inline Skill("simplify:simplify") when workers are unavailable. This is a required skill invocation for code changes, not a discretionary manual review.
     • If intensity == normal AND code_review.codex.enabled_in_normal: true AND dev-loop:codex-review-worker ∉ DEP_DRIFT AND codex:codex-rescue ∉ DEP_DRIFT → append dev-loop:codex-review-worker.
     • If intensity == high AND code_review.codex.enabled_in_high: true AND both refs not in DEP_DRIFT → append dev-loop:codex-review-worker.
     • If code_review block absent → defaults to base-only (preserves pre-v1.15.0 behavior). Schema: templates/project-config.md § Code review. Setup flow: setup-dev-loop/SKILL.md Section M. Resolve vault_auto_commit — read from config, default true. Store as session variable VAULT_AUTO_COMMIT. When true, SAVE step 7 commits dirty vault files; AUDIT step 13 warns if tree is dirty.

     Resolve vault_sync — parse the vault_sync block from config.

     • If block is absent: default peer_aware: true when vault_auto_commit: true, otherwise false. Default lock_timeout_seconds: 30, retry_budget: 3.
     • If peer_aware: false (explicit or defaulted) → store VAULT_SYNC_PEER_AWARE = false.
     • If peer_aware: true AND query_vault in BACKEND_CAPS:
       • Verify skillwiki >= v0.6.0 by checking for --acquire-lock flag: skillwiki sync --help 2>/dev/null | grep -q "acquire-lock"
       • If available → store VAULT_SYNC_PEER_AWARE = true, VAULT_SYNC_LOCK_TIMEOUT = lock_timeout_seconds (default 30), VAULT_SYNC_RETRY_BUDGET = retry_budget (default 3).
       • If skillwiki < v0.6.0 → store VAULT_SYNC_PEER_AWARE = false, emit one-time warning: "vault_sync.peer_aware requires skillwiki

         = v0.6.0 — upgrade skillwiki to enable peer-aware vault push." Always initialize VAULT_SYNC_DEFERRAL_COUNT = 0 at cycle start (per-cycle scope — not session-scoped). Resolve presync_skill — parse from vault_sync.presync_skill: auto-detect (default), always, or never. Store as VAULT_SYNC_PRESYNC_SKILL. When auto-detect, probe $VAULT/.claude/skills/wiki-presync/SKILL.md at cycle start; cache result as VAULT_PRESYNC_AVAILABLE (bool).

     Resolve investigate — parse the investigate block from config.

     • If block is absent → store INVESTIGATE_MAX_ITEMS = 5, INVESTIGATE_TOPIC_SEEDS = [] (will fall back to idle_deep_research.topic_seeds at runtime).
     • If block present: read max_items (default 5), topic_seeds (default []). Store as session variables.
     • Investigate mode itself is always available when query_vault in BACKEND_CAPS — the config section only controls tuning parameters.

     Resolve preflight — parse the preflight block from config. Store as PREFLIGHT_POLICY. If the block is absent, use: enabled: true, default_limit: 5, default_lanes: [work, captures, hygiene], require_approved_spec_and_plan: true, unattended_not_ready_behavior: skip, and defaults: {}. Validate default_limit is a positive integer and default_lanes

Truncated - read the full file at https://github.com/karlorz/agent-skills/blob/44d4e0c268132bb7df1d19801a93eed501534e06/skills/dev-loop/skills/dev-loop/SKILL.md.