Skill Pipeline

Skill Pipeline

The conductor, not a player. This skill classifies tasks, selects the pipeline variant, calibrates depth, and orchestrates handoffs between skills. It produces no artifacts of its own — its output is routing decisions that activate other skills.

Task Classification

On every coding task, classify before acting. Evaluate scope signals and map to a task class.

Input signals: file count, task description, existing plan/handoff files, batch indicators, CI environment.

Task received
  │
  ├─ Trivial (typo, rename, version bump)
  │  → No skills. Just do it.
  │
  ├─ Small (isolated fix, single-file, <10 logic lines)
  │  → verify-gate + simplify-and-harden
  │
  ├─ Medium (feature in known area, 2-5 files)
  │  → intent-framed-agent + verify-gate + simplify-and-harden
  │
  ├─ Large (complex refactor, new architecture, unfamiliar codebase, high-risk logic)
  │  → Full standard pipeline
  │  → Recommend /plan-interview before starting
  │
  ├─ Long-running (multi-session, high context pressure, prior handoff exists)
  │  → Full standard pipeline with context-surfing as critical skill
  │
  └─ Batch (multiple features from spec, 5+ discrete tasks, issue triage)
     → Team-based pipeline (agent-teams-simplify-and-harden)

When uncertain, start with Medium. Add skills if drift or quality issues appear mid-task.

For detailed heuristics, edge cases, and examples: read references/classification-rules.md.

Pipeline Selection

Route task class to the right variant:

Heuristic: Standard pipeline for depth (single complex feature). Team-based pipeline for breadth (batch of tasks). CI pipeline when CI=true or GITHUB_ACTIONS=true.

Activation Sequences

Standard Pipeline (Inner Loop)

pre-flight-check (SessionStart hook — surfaces prior learnings + heals)
  → classify
  → (recommend /plan-interview if Large or Long-running)
  → intent-framed-agent (at planning-to-execution transition)
  → context-surfing (auto-activates when intent frame + plan exist; concurrent with intent monitoring)
  → [IMPLEMENTATION]
  → self-healing  ← inner-loop recovery primitive; called whenever a command/test/build/external call fails or a helper is missing.
  →                Diagnoses, patches, verifies, files HEAL- entry. Resumes when verified.
  → verify-gate (compile + test + lint; fix loop if red — fix loop calls self-healing)
  → simplify-and-harden (post-completion, if non-trivial diff)
  → self-improvement (on errors, corrections, S&H learning candidates, recurring heal handoffs)

Skill-by-class activation:

Team-Based Pipeline

classify (Batch)
  → (recommend /plan-interview if no spec exists)
  → agent-teams-simplify-and-harden
    ├─ Team lead emits Intent Frame #1
    ├─ Phase 1: parallel implementation agents
    ├─ verify-gate (compile + test + lint)
    ├─ Phase 2: parallel audit agents (simplify, harden, spec)
    ├─ Fix loop (up to 3 audit rounds)
    └─ Learning loop output
  → self-improvement

CI Pipeline

classify (CI detected)
  → simplify-and-harden-ci (headless scan, PR changed files only)
  → self-improvement-ci (pattern aggregation, promotion recommendations)

Outer Loop Pipeline

The outer loop runs across sessions, not within them. Trigger on cadence (weekly, sprint boundary) or when pre-flight-check surfaces promotion-ready patterns.

learning-aggregator (read .learnings/, find patterns, rank promotion candidates)
  → harness-updater agent (apply promotions to CLAUDE.md, AGENTS.md, copilot-instructions.md)
  → eval-creator (create permanent test cases from promoted patterns)
  → eval-creator run (regression check on all existing evals)

When to trigger the outer loop:

• Weekly: recommended minimum cadence
• Sprint boundary: after a burst of sessions
• When pre-flight-check reports promotion-ready count > 3
• After a significant incident or recurring failure
• Manually: user invokes /learning-aggregator

Outer loop is always human-gated. learning-aggregator produces a gap report. harness-updater shows diffs for approval. No automatic writes to instruction files without human review.

Depth Calibration

Not just which skills — how deep each goes:

Handoff Rules

Artifacts flow between skills. The orchestrator ensures each skill receives what it needs.

Key handoffs:

1. Plan file (docs/plans/plan-NNN-<slug>.md) — produced by plan-interview, consumed by intent-framed-agent (context), context-surfing (wave anchor), agent-teams (task extraction).

2. Intent Frame — produced by intent-framed-agent, consumed by context-surfing (wave anchor strengthening). Copied into handoff files on drift exit.

3. Handoff file (.context-surfing/handoff-[slug]-[timestamp].md) — produced by context-surfing on drift exit, consumed by next session for resume.

4. Verify-gate signal — produced by verify-gate (pass/fail + diagnostics), consumed by simplify-and-harden (only activates after green gate) and the heal loop (on failure — verify-gate hands the diagnostics to self-healing, which diagnoses + patches + re-verifies, then signals verify-gate to re-check).

5. HEAL entries + artifacts (.learnings/HEALS.md, .learnings/heals/<HEAL-ID>/) — produced by self-healing, consumed by pre-flight-check (surfaces prior heals at session start by Pattern-Key / Active-Context), learning-aggregator (cross-session recurrence analysis), and self-improvement (when Handoff block flags promotion at Recurrence ≥ 3).

6. Learning candidates (learning_loop.candidates) — produced by simplify-and-harden and agent-teams, consumed by self-improvement for pattern tracking.

7. Learning entries (.learnings/*.md) — produced by self-improvement, consumed by learning-aggregator for cross-session analysis and by pre-flight-check at session start.

8. Gap report — produced by learning-aggregator, consumed by harness-updater agent for promotion and eval-creator for test case generation.

9. Eval cases (.evals/cases/*.md) — produced by eval-creator, consumed by regression runs and surfaced by pre-flight-check.

Precedence: If context-surfing and intent-framed-agent both fire simultaneously, context-surfing's exit takes precedence. Degraded context makes scope checks unreliable.

For the full artifact/signal/budget table: read references/handoff-matrix.md.

Decision Points

The orchestrator intervenes at these moments:

Task Arrival

Classify the task. Select pipeline variant and depth. Emit routing decision. If Large/Long-running, recommend /plan-interview. If Batch, recommend team-based variant.

Plan Approval

When user approves a plan from plan-interview, flow directly into the execution stage — no separate "should I proceed?" prompt. This means activating intent-framed-agent to emit an Intent Frame. The intent frame itself still requires user confirmation before coding begins (that confirmation is part of intent-framed-agent, not an extra gate). Populate task tracking with checklist items.

Planning-to-Execution Transition

When no plan-interview was used and the user signals readiness ("go ahead", "implement this", "let's start"), activate intent-framed-agent. Emit Intent Frame. Wait for user confirmation of the frame before coding.

Failure mid-implementation

A command, test, build, lint, or external call fails before verify-gate even runs (or any other mid-task gap appears — missing helper, env drift, API change). Route into self-healing: diagnose, patch, verify, file the HEAL entry. Resume execution from the working state. Most heals are recurrences — self-healing searches HEALS.md by Pattern-Key first.

Implementation Complete

Activate verify-gate to run compile, test, and lint checks. If any fail, route into self-healing for the diagnosis/patch/verify loop (up to 3 attempts per phase). After each heal, verify-gate re-runs the checks. Once all checks pass and the diff meets the non-trivial threshold (see references/classification-rules.md), activate simplify-and-harden. If the diff is trivial, signal completion directly after verify-gate passes.

Drift Detected

If context-surfing fires a drift exit, stop execution. Write handoff file. If the task was classified below Large, consider re-classifying upward for the next session.

Session Resume

Check for handoff files in .context-surfing/. If found, read completely. Re-establish context from handoff. Re-classify if needed. Resume from recommended re-entry point.

Overrides

Users can override any routing decision:

• Force depth: depth=small / depth=large — override classification
• Force variant: variant=teams / variant=standard — override pipeline selection
• Skip review: --no-review — skip simplify-and-harden
• Force planning: invoke /plan-interview on any task regardless of classification
• Skip all skills: user says "just do it" on a non-trivial task — respect the override

Re-classification

Tasks can change class mid-execution. Watch for:

• Escalation signals: scope expanded beyond original estimate, many more files affected than expected, context-surfing drift exit, intent-framed-agent detects significant scope change
• De-escalation signals: task turns out simpler than planned, plan reveals minimal changes needed

When re-classification is warranted: 1. Note the signal that triggered re-classification 2. Adjust active skills (add or remove pipeline stages) 3. If escalating to Large: recommend /plan-interview if no plan exists 4. If de-escalating: drop unnecessary stages, proceed with lighter pipeline

Anti-Patterns

• Do NOT re-implement skill logic. This skill classifies and dispatches. Each individual skill owns its own procedure.
• Do NOT auto-invoke plan-interview. It is a human gate. Recommend it; let the user decide.
• Do NOT create a third monitoring layer. During execution, intent-framed-agent monitors scope and context-surfing monitors quality. The orchestrator dispatches at decision points, then gets out of the way.
• Do NOT override individual skill guardrails. If simplify-and-harden has a 20% budget cap, the orchestrator respects it.
• Do NOT force skills on trivial tasks. The pipeline exists to help, not to slow down simple work.

Pipeline Variant Details

For complete step-by-step walkthroughs of each variant including hybrid scenarios and session resume: read references/pipeline-variants.md.

Task Classification Rules

Detailed heuristics for classifying incoming tasks. The orchestrator in SKILL.md uses these to route tasks through the correct pipeline variant and depth.

Classification Signals

Evaluate these signals to determine task class:

File scope

• Single file or isolated function → Small
• 2-5 files in a known area → Medium
• 5+ files or cross-cutting concern → Large or Batch
• Unfamiliar codebase or new architecture → Large regardless of file count

Task description keywords

• Typo, rename, fix wording, bump version → Trivial
• Bug fix, patch, isolated fix → Small
• Add feature, implement, integrate → Medium or Large (depends on scope)
• Refactor, migrate, rewrite, redesign → Large
• "List of issues", "batch of features", "from this spec" → Batch

Existing artifacts

• Plan file exists in docs/plans/ → at least Medium
• Handoff file exists in .context-surfing/ → session resume, likely Large or Long-running
• Spec or issue list provided → Batch

Environment

• CI=true or GITHUB_ACTIONS=true → CI variant
• Multi-session work or user mentions context pressure → Long-running

Task Classes

Trivial

Examples: fix a typo, rename a variable, update a version string, fix a broken link Signals: single-line change, no logic change, no risk Pipeline: None — just do it

Small

Examples: isolated bug fix, single-file feature addition, test fix Signals: 1 file, <10 lines of logic change, low risk, known area Pipeline: verify-gate + self-healing (on failure) + simplify-and-harden (post-completion)

Medium

Examples: feature in a known area spanning 2-5 files, adding an API endpoint, component refactor Signals: 2-5 files, known patterns, moderate complexity Pipeline: intent-framed-agent + verify-gate + self-healing (on failure) + simplify-and-harden

Large

Examples: complex refactor, new architecture, unfamiliar codebase, auth system changes, database migration Signals: 5+ files OR unfamiliar area OR high-risk logic (auth, data access, concurrency) Pipeline: Full standard pipeline. Recommend /plan-interview before starting.

Long-running

Examples: multi-session refactor, large migration, greenfield module in complex codebase Signals: task cannot complete in one session, high context pressure, prior handoff files exist Pipeline: Full standard pipeline with context-surfing as the critical skill

Batch

Examples: implementing multiple features from a spec, fixing a list of review findings, hardening multiple files Signals: 5+ discrete tasks, spec or issue list provided, breadth over depth Pipeline: Team-based pipeline (agent-teams-simplify-and-harden)

Non-Trivial Code Change Definition

The canonical definition lives in skills/simplify-and-harden/SKILL.md (lines 60-69). Refer to that source for the full rule. In short: the diff must touch at least one executable source file AND include either >= 10 changed logic lines or a high-impact logic change. Docs-only, config-only, tests-only, and generated artifacts are non-trivial = false.

Planning Depth Calibration

From plan-interview, match refinement depth to classification:

Edge Cases

• Task escalation: A Medium task can reveal itself as Large mid-execution. If context-surfing fires a drift exit or intent-framed-agent detects significant scope expansion, re-classify upward and add pipeline stages.
• User override: User can force depth (depth=small) or variant (variant=teams) regardless of classification.
• Ambiguous scope: When uncertain, start with Medium. Add skills if drift or quality issues appear.
• Hybrid tasks: A task with both a single complex feature AND several small fixes → route the complex feature through standard pipeline, batch the fixes through teams, or do the complex feature first then batch the rest.

Handoff Matrix

Artifact flow, signal routing, precedence rules, and budget constraints across the skill pipeline.

Artifact Flow

Signal Routing

Precedence Rules

1. context-surfing exit > intent-framed-agent Intent Check — If both fire simultaneously, resolve context degradation first. Degraded context makes scope checks unreliable. 2. simplify-and-harden re-entry guard — The skill does not run twice on the same task. No re-entry loops. 3. Plan-interview is a human gate — Never auto-invoke. Recommend when task classifies as Large, but user decides. 4. Quality gates are non-negotiable (for agent-teams): clean compile, tests pass, exit condition met, no TODO/FIXME without tasks.

Budget Constraints

Context File Loading

From context-surfing, always load at activation:

• CLAUDE.md — agent configuration, conventions, constraints
• AGENTS.md — multi-agent setup, role definitions
• README.md — project intent and structure
• Any .md in project root

Load on demand when relevant:

• .md files in skills/, docs/, .learnings/
• SKILL.md files for skills being invoked

Learning Loop Integration

Pattern keys emitted by code review skills:

• Simplify: simplify.dead_code, simplify.naming, simplify.control_flow, simplify.over_abstraction
• Harden: harden.input_validation, harden.authorization, harden.error_handling, harden.injection_vectors, harden.secrets_exposure

Promotion threshold: recurrence count >= 3, seen across >= 2 distinct tasks, within 30-day window.

Pipeline Variants

Detailed walkthroughs of each pipeline variant. The orchestrator in SKILL.md selects the variant; this reference documents the full execution flow for each.

Standard Pipeline

For single-feature depth work. Not all stages activate for every task class — see the activation table in SKILL.md for which skills apply at each depth.

• Medium: intent-framed-agent + simplify-and-harden (no planning, no context-surfing)
• Large: Full pipeline including plan-interview (recommended) and context-surfing
• Long-running: Full pipeline with context-surfing as the critical skill

Full pipeline (Large/Long-running):

[plan-interview] → [intent-framed-agent] ⟂ [context-surfing] → [verify-gate] → [simplify-and-harden] → [self-improvement]
                                                                    ↳ on failure → [self-healing] (diagnose → patch → verify → file HEAL) → re-verify

Step-by-step

1. Classify — skill-pipeline determines task class and recommends pipeline depth.

2. Plan (optional, recommended for Large) — User invokes /plan-interview. Structured interview across 4 domains (technical constraints, scope boundaries, risk tolerance, success criteria). Produces docs/plans/plan-NNN-<slug>.md with iterative refinement.

3. Intent Frame — intent-framed-agent activates at the planning-to-execution transition. Emits Intent Frame with outcome, approach, constraints, success criteria, complexity. User confirms before coding begins.

4. Execute with monitoring — Implementation proceeds. Two concurrent monitors:

• intent-framed-agent monitors scope (are we doing the right thing?)
• context-surfing monitors context quality (are we still capable of doing it well?)
• If both fire simultaneously, context-surfing exit takes precedence.

5. Heal on failure (inner-loop recovery) — Any time a command, test, build, lint, missing helper, environment drift, or external service issue blocks progress, route into self-healing. The loop: diagnose root cause, write/apply the patch (artifacts under .learnings/heals/<HEAL-ID>/ only if files are generated), verify by re-running the failing operation, file the verified HEAL- entry to .learnings/HEALS.md. Most heals are recurrences — search HEALS.md by Pattern-Key first. At Recurrence ≥ 3 across distinct tasks, append a Handoff block to flag the entry for promotion via self-improvement.

6. Review — On task completion, simplify-and-harden runs three passes:

• Simplify (clarity, dead code, naming, control flow)
• Harden (validation, injection vectors, auth, secrets)
• Document (max 5 comments on non-obvious decisions)
• Cosmetic fixes auto-apply; refactors require human approval.

7. Learn — self-improvement ingests learning_loop.candidates from S&H plus Handoff blocks from recurring heals. Logs entries with pattern_key. Promotes recurring patterns (>= 3 occurrences, >= 2 tasks, 30 days) to project memory.

Wave Anchor Composition

• Full pipeline: intent frame + plan file + Entire CLI session state (if available)
• Partial pipeline: whichever of intent frame or plan exists, plus project context files
• Standalone: user task description + project context files

Session Resume

If a prior session produced a handoff file (.context-surfing/handoff-[slug]-[timestamp].md): 1. Read handoff file completely before doing anything else 2. If original session used full pipeline: re-establish plan and intent frame from handoff 3. If standalone: use handoff's task description and drift notes to re-ground 4. Pick up context-surfing from recommended re-entry point

---

Team-Based Pipeline

For breadth work (Batch tasks: multiple features, issue triage, batch hardening).

[plan-interview] → [agent-teams-simplify-and-harden] → [self-improvement]

Step-by-step

1. Classify — skill-pipeline identifies batch work and routes to team-based variant.

2. Plan (optional) — If a plan file exists, agent-teams extracts tasks from it. If no plan, the team lead runs a brief inline planning phase.

3. Team Lead Intent Frame — Team lead emits Intent Frame #1 before spawning the team.

4. Phase 1: Implement — Parallel general-purpose agents work on assigned tasks. Wait for all to complete. Verify: clean compile + tests pass.

5. Phase 2: Audit — Parallel Explore (read-only) agents run three audit dimensions:

• simplify-auditor: dead code, naming, control flow, over-abstraction
• harden-auditor: validation, injection vectors, auth, secrets, data exposure
• spec-auditor: completeness versus plan/spec
• All use read-only access to prevent silent fixes.

6. Process Findings — Categorize by severity:

• Critical/High → create fix task
• Medium → include in next round
• Low → fix inline or note in summary
• Refactor gate: "Would a senior engineer say this is clearly wrong, not just imperfect?"

7. Drift Check — Team lead re-reads intent frame + plan between rounds. Are audit findings pulling scope off course?

8. Loop — Up to 3 audit rounds. Exit when:

• Clean audit (zero findings), OR
• Low-only round (fix inline, skip re-audit), OR
• Loop cap reached (3 rounds; resolve critical/high, log others)

9. Learn — Emit learning loop candidates for self-improvement.

Budget Guidance

• Track cumulative diff growth
• If > 30% above original implementation diff: skip medium/low simplify findings, focus on harden patches and spec gaps

---

CI Pipeline

For automated pull request review in GitHub Actions or similar CI environments.

[simplify-and-harden-ci] → [self-improvement-ci]

Step-by-step

1. Detect — skill-pipeline checks for CI environment variables (CI=true, GITHUB_ACTIONS=true).

2. Review — simplify-and-harden-ci runs headless scan on PR changed files only:

• No code mutations (review-only)
• Findings posted as PR comment and/or check run
• Structured YAML output
• Configurable merge gating by severity

3. Learn — self-improvement-ci reads PR check results and S&H-CI findings:

• Deduplicates by stable pattern_key
• Emits promotion-ready suggestions when recurrence thresholds met
• No interactive prompts

Limitations

• CI agents lack peak implementation context — findings are review signals, not intent-aware rewrites.
• Route promotion-ready patterns back to interactive self-improvement for durable rule generation.

---

Hybrid Scenarios

Escalation: Standard to Teams

A Medium task reveals itself as requiring batch work mid-execution. The orchestrator: 1. Notes escalation signal (scope expanded, many files affected) 2. Suggests switching to team-based variant 3. Preserves existing intent frame and plan as input to agent-teams

De-escalation: Large to Small

Planning reveals the task is simpler than initially thought. The orchestrator: 1. Adjusts pipeline depth (drop plan-interview, maybe drop intent-framed-agent) 2. Proceed with lighter pipeline

Mixed: Complex feature + small fixes

Route the complex feature through standard pipeline first. After completion, batch the small fixes through teams or handle them as individual Small tasks with S&H only.