Workflow orchestration, certainty-graded quality rules, and task pipelines for b00t agents

version
0.1.0
GitHub stars
16

Install

/plugin install next-task@b00t-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add elasticdotventures/_b00t_.

Contents

Discovered from source

Skills 6

Certainty Grade Framework

All agent findings MUST include a certainty grade. Grade determines action path.

Grades

GradeBasisAction
HIGHDeterministic: regex match, static check, type error, compiler outputAuto-fix permitted
MEDIUMHeuristic: code ratio analysis, pattern frequency, structural smellFlag for review
LOWAI judgment: semantic meaning, intent, contextual inferenceHuman gate required

Steps

  1. Identify the finding type. # output: finding_type (deterministic|heuristic|semantic)
  2. Assign grade:
    • HIGH if finding_type == deterministic (provable without AI)
    • MEDIUM if finding_type == heuristic (pattern-based, probabilistic)
    • LOW if finding_type == semantic (requires AI reasoning)

    output: certainty (HIGH|MEDIUM|LOW)

  3. Attach grade to finding in output. Format: [HIGH] <finding>, [MEDIUM] <finding>, [LOW] <finding>
  4. For batched findings, group by certainty. # output: grouped_findings

Action Gates

HIGH  → auto-apply fix if safe, log result
MEDIUM → surface to user, suggest fix, await confirmation
LOW   → block action, require explicit human approval, explain reasoning

Output Format

[HIGH]   console.log() at src/foo.ts:42 — remove (debug artifact)
[MEDIUM] function doThing() lacks error handling — review
[LOW]    variable naming may be misleading given domain context — human review

Integration

Used by: /next-task, /code-quality, all agents that produce findings. b00t MUST grade all MCP tool outputs before acting on them.

Code Quality Rules

Uses certainty-grade framework. Runs deterministic checks first (code), AI analysis second (reasoning).

Steps

  1. Run HIGH certainty checks (no AI needed). # output: high_findings[]
  2. Run MEDIUM certainty checks (heuristics). # output: medium_findings[]
  3. Run LOW certainty checks (AI judgment). # output: low_findings[]
  4. Apply certainty-grade to each finding.
  5. Group: auto-fixable (HIGH) vs needs-review (MEDIUM) vs human-gate (LOW).
  6. Report summary with counts.

HIGH Certainty Rules (Deterministic)

AI Artifact Detection:

  • console.log( / print( / println!( in non-test code
  • TODO, FIXME, HACK, XXX comments without issue reference
  • debugger; statements
  • Placeholder values: "TODO", "FIXME", "placeholder", "example.com"
  • Commented-out code blocks (3+ consecutive commented lines)

b00t Violations:

  • Direct pip install (MUST use uv pip install)
  • docker run without podman (MUST use podman)
  • Raw templates read without b00t learn
  • Hardcoded API keys or secrets (entropy check)

Language-Specific:

  • unwrap() in Rust production code (outside tests)
  • except: pass in Python
  • any type in TypeScript without justification comment

MEDIUM Certainty Rules (Heuristic)

Documentation Ratios:

  • Functions >20 lines without docstring/comments
  • Public API without documentation
  • File doc ratio < 10% (comment lines / total lines)

Code Smell Patterns:

  • Functions >50 lines (single responsibility violation)
  • Nesting depth >4 (cognitive complexity)
  • Duplicate code blocks (>10 identical lines across files)
  • Magic numbers without named constants

b00t Alignment:

  • Missing # 🤓 tribal knowledge on non-idiomatic patterns
  • Missing error handling at system boundaries
  • Tests that mock internal code (MUST mock at system boundary only)

LOW Certainty Rules (AI Judgment)

  • Variable/function naming clarity relative to domain
  • Algorithm choice vs alternative approaches
  • Missing edge case handling (contextual)
  • Architectural concerns (tight coupling, abstraction leaks)

Output Format

Code Quality Report: <file/scope>
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[HIGH]   3 findings — auto-fixable
  ✗ console.log() at src/app.ts:12
  ✗ TODO without issue at lib/utils.rs:88
  ✗ unwrap() in production at src/main.rs:45

[MEDIUM] 2 findings — needs review
  ⚠ process_data() at src/etl.py:100 — 67 lines, consider split
  ⚠ public fn without docs at src/api.rs:23

[LOW]    1 finding — human gate
  ? naming: `handle_thing()` may be ambiguous in payment context

Auto-fix available: 3 | Review required: 2 | Human approval: 1

Integration

Invoke via: /next-task (pre-merge gate), inline during implementation. All fixes apply certainty-grade before executing.

/deslop — AI Artifact Removal

Three-phase pipeline: deterministic first, heuristic second, AI last. Never removes without certainty grade.

Steps

  1. Identify scope (file, directory, or git diff). # output: scope_paths[]
  2. Run Phase 1 (HIGH). # output: high_findings[]
  3. Run Phase 2 (MEDIUM). # output: medium_findings[]
  4. Run Phase 3 (LOW). # output: low_findings[]
  5. Apply certainty-grade to all findings.
  6. AUTO-REMOVE all HIGH findings after displaying list. ← confirmation optional via --dry-run
  7. Surface MEDIUM findings for Operator review. ← HUMAN GATE
  8. Present LOW findings with reasoning; apply only if Operator confirms.
  9. Commit cleanup: git commit -m "chore: deslop AI artifacts" # output: commit_sha

Phase 1: HIGH Certainty (Regex — auto-remove)

Only patterns that are unambiguously debug/leftover artifacts with near-zero false positive rate. Do NOT auto-remove patterns that are context-dependent — those belong in Phase 2.

console\.log\(          → JS/TS debug output (lib files only, not scripts)
\bpdb\.set_trace\(\)    → Python interactive debugger — always wrong in committed code
debugger;               → JS/TS breakpoint — always wrong in committed code
except:\s*pass          → Python silent exception swallow
// TODO(?!.*#[0-9]+)    → Rust/JS TODO without issue reference (use # prefix for Python/shell)
# TODO(?!.*#[0-9]+)     → Python/Shell TODO without issue reference
// FIXME(?!.*#[0-9]+)   → Rust/JS FIXME without issue reference
# FIXME(?!.*#[0-9]+)    → Python/Shell FIXME without issue reference
// HACK\b               → Hack marker (Rust/JS/TS)
// XXX\b                → Unresolved marker (Rust/JS/TS)

Respect file-level # deslop:ignore annotation to skip a file. Skip tests/, *_test.*, *.spec.*, *_spec.*, src/bin/, src/main.rs.

Removed from HIGH (too many false positives — demoted to MEDIUM):

  • println!( — valid in Rust binary crates, CLI entry points; only an artifact in lib crates
  • print( — standard output in Python scripts, not always debug
  • "placeholder" — valid HTML attribute, CSS, UI framework value
  • "example.com" — IANA-reserved domain; legitimately used in docs, RFC examples, tests, config templates
  • .unwrap() — requires context: legitimate after .contains() guards, in main.rs, prototypes

Phase 2: MEDIUM Certainty (Heuristic — surface for review)

  • Commented-out code blocks: 3+ consecutive // or # lines that parse as valid code
  • Verbosity patterns: function docstrings longer than the function body
  • Over-explanation comments: comments that restate what the next line obviously does ex: # increment i by 1 before i += 1
  • Duplicate log statements: same message logged in consecutive lines
  • Dead imports: import X where X never appears in file body
  • println!( in Rust lib crate files (not main.rs, not src/bin/, not #[cfg(test)])
  • print( in Python non-script files (not __main__, not CLIs, not test helpers)
  • .unwrap() in Rust: flag if there is no preceding .is_some()/.contains()/assert guard and not in main.rs or test
  • "placeholder" as a runtime value (not as an HTML/CSS attribute name or UI label)
  • "example.com" in non-documentation Rust/Python source as a live URL (not in doc comments, not in tests)

Phase 3: LOW Certainty (AI judgment — human gate)

  • Placeholder logic: functions that only return None / pass / throw new Error("not implemented")
  • Scaffolding that was never filled in
  • Overengineered abstractions added speculatively ("we might need this later")
  • Excessive type casting or conversion that AI commonly adds defensively

Flags

/deslop                    # Run on git diff (staged + unstaged)
/deslop --path <path>      # Specific file or directory
/deslop --dry-run          # Show findings only, no changes
/deslop --phase <1|2|3>    # Run specific phase only
/deslop --skip-low         # Skip Phase 3 (faster)

Output

deslop report: src/
━━━━━━━━━━━━━━━
[HIGH]   removed 4 artifacts automatically
  ✓ console.log() at src/app.ts:12
  ✓ TODO (no issue) at src/utils.ts:88
  ✓ debugger; at src/debug.ts:3
  ✓ .unwrap() at src/main.rs:45

[MEDIUM] 2 findings — awaiting review
  ⚠ commented-out block at src/parser.ts:55-62
  ⚠ dead import `useState` at src/foo.tsx:2

[LOW]    1 finding — human gate
  ? scaffold fn `processPayment()` returns None — was this implemented?

Integration

Runs automatically at IMPLEMENT phase of /next-task. Can be invoked standalone pre-PR.

/drift-detect — Documentation-Code Alignment

Principle: code does deterministic collection; AI does one semantic analysis pass. Avoids multi-agent token waste — single well-prompted synthesis call.

Steps

  1. Identify scope: README, CLAUDE.md, inline docstrings, docs/, .tomllm comments. # output: doc_files[]
  2. Identify code: public API surfaces, CLI commands, MCP tools, data schemas. # output: code_surfaces[]
  3. COLLECT deterministic facts from code (no AI). # output: code_facts{}
  4. COLLECT documented claims from docs (no AI). # output: doc_claims{}
  5. DIFF: find claims in docs not evidenced in code_facts. # output: raw_drift[]
  6. Single LLM call: semantic analysis of raw_drift to grade and explain. # output: graded_drift[]
  7. Group by certainty-grade; present report.

Phase 1: Deterministic Collection (Code → Facts)

Extract without AI:

CLI commands     → grep `#\[command\]` / `clap::Command` / argparse / click decorators
MCP tools        → grep `#[tool]` / tool schema definitions
Public functions → AST: all `pub fn`, `export function`, `def` without leading `_`
Config keys      → grep TOML/JSON schema keys in datum files
Environment vars → grep `env!()`, `os.getenv`, `process.env.`
API endpoints    → grep route decorators (`@app.get`, `#[get]`, `router.get`)

Phase 2: Deterministic Collection (Docs → Claims)

Extract without AI:

README commands  → grep ` ``` ` blocks containing CLI invocations
Documented envs  → grep `ENV_VAR_NAME` pattern in .md files
Skill triggers   → grep activation phrases in SKILL.md files
Datum fields     → parse TOML keys from .tomllm files

Phase 3: Single LLM Semantic Analysis

Pass code_facts and doc_claims to one analysis call:

Prompt: "Given these documented claims and these code facts, identify:
1. Claims in docs not supported by code (doc leads code — stale)
2. Code surfaces not mentioned in docs (code leads docs — undocumented)
3. Semantic mismatches where names/behavior differ
Grade each finding HIGH/MEDIUM/LOW certainty."

Drift Categories

TypeDescriptionGrade
stale-docDocs describe removed/changed featureHIGH if name mismatch, MEDIUM if semantic
undocumentedCode exists, no docsMEDIUM
mismatchDocs and code describe different behaviorLOW (AI judgment)
version-skewDocs reference old version numbers/flagsHIGH

Flags

/drift-detect                  # Full repo scan
/drift-detect --path <dir>     # Scope to directory
/drift-detect --focus docs     # Only stale-doc findings
/drift-detect --focus code     # Only undocumented findings
/drift-detect --fix            # Auto-stub missing docs (MEDIUM certainty only)

Output

drift-detect report: .b00t/
━━━━━━━━━━━━━━━━━━━━━━━━━━━
[HIGH]   2 stale documentation findings
  ✗ README references `b00t run` — command removed in cli v0.8
  ✗ CLAUDE.md documents `--model-size` flag — not in current clap schema

[MEDIUM] 3 undocumented code surfaces
  ⚠ `b00t hive activate` — no README entry
  ⚠ MCP tool `b00t_agent_vote_create` — not in docs
  ⚠ env var `VLLM_DTYPE` — not in .env.example

[LOW]    1 semantic mismatch
  ? SKILL.md says deslop "auto-removes"; code-quality rules say "surfaces for review" — reconcile

Total: 6 findings | Auto-fixable stubs: 3 | Stale to remove: 2 | Human review: 1

Integration

Runs at REVIEW phase of /next-task. Invoked standalone post-implementation to check docs kept current.

Model Routing

NEVER use frontier model for mechanical work. Route by cognitive tier. Reads routing table from _b00t_/model-routing.tomllm. Falls back to hardcoded tiers.

Cognitive Tiers

TierTasksb00t Models (in priority order)
small (sm0l)grep, lint, classify, route, test pass/failhaiku, local sm0l
chunky (ch0nky)implement, refactor, debug, code reviewqwen3-coder-local (RTX 3090), sonnet
frontierarchitecture, security, novel design, planningopus, sonnet

Steps

  1. Classify the task type. # output: task_type
  2. Map task_type → cognitive tier. # output: tier (sm0l|ch0nky|frontier)
  3. Load routing config: b00t learn model-routing via MCP or CLI — NEVER read .tomllm directly. # output: available_models[]
  4. Select best available model for tier (prefer local, fallback frontier). # output: selected_model
  5. Check resource gate: b00t hive status — ensure RAM/GPU available. # output: resource_ok
  6. If resource gate fails: escalate one tier up or queue. # output: model_or_queue
  7. Return {model, tier, rationale} for caller to invoke.

Task → Tier Mapping

small sm0l (Haiku / local 3B):

  • Running tests, checking lint output
  • Classifying/routing messages
  • Extracting structured data from well-defined input
  • File diffing, counting, summarizing short text
  • Executing known shell commands

chunky ch0nky (qwen3-coder-local → Sonnet fallback):

  • Writing or refactoring code
  • Debugging with stack traces
  • Multi-file code review
  • Translating between languages/formats
  • Implementing skills from SKILL.md spec

frontier (Opus → Sonnet fallback):

  • System architecture decisions
  • Security threat modeling
  • Novel algorithm design
  • Planning complex multi-step workflows
  • Evaluating ambiguous requirements

Output Contract to Executive Context

Executive context is costly. Sub-agents MUST return compressed summaries:

TierMax output to executive
sm0lPASS or FAIL: <name> <5 lines>
ch0nkydiff + test result (no full file dumps)
frontierstructured decision with rationale

Resource Awareness

Before invoking ch0nky/frontier check hive:

b00t hive status  # output: RAM free, GPU VRAM free, active profile

Anti-pattern: running vLLM (qwen3-coder, 20GB VRAM) + HuggingFace download simultaneously on 24GB.

Integration

Used by /next-task at each phase to select model. Used by b00t-mcp agent delegation. Load via: b00t learn model-routing (MCP preferred, CLI fallback)

🤓 NEVER read b00t/*.tomllm directly — always use b00t learn/MCP which applies guardrails, guru enrichment & tribal knowledge

/next-task Workflow Orchestration

Gated pipeline: DISCOVER → PLAN → IMPLEMENT → REVIEW → SHIP. State persists in git (branch + commit messages). Each phase can resume independently.

Phases

Phase 1: DISCOVER

  1. Check taskmaster-ai for next prioritized task. # output: task_id, task_description
  2. If no taskmaster-ai, check git issues: gh issue list --label next-task --limit 1 # output: issue_id
  3. If none, ask Operator to specify. # output: task_clarified
  4. Confirm task scope with Operator before proceeding. ← HUMAN GATE
  5. Create isolated branch: git checkout -b task/<id>-<slug> # output: branch_name

Phase 2: PLAN

  1. Map affected files and dependencies using repo structure. # output: affected_files[]
  2. Identify risks (breaking changes, security, performance). # output: risk_assessment
  3. Write implementation plan (steps, test strategy, rollback). # output: plan_md
  4. Apply certainty-grade to each plan step. # output: graded_plan
  5. Present plan to Operator. ← HUMAN GATE

Phase 3: IMPLEMENT

  1. Write failing tests first (TDD). # output: test_files[]
  2. Implement minimum code to pass tests. # output: changed_files[]
  3. Run code-quality skill on all changed files. # output: quality_report
  4. Run deslop skill on all changed files. # output: deslop_report
  5. AUTO-FIX all HIGH certainty findings (quality + deslop). # output: auto_fix_log
  6. Surface MEDIUM findings to Operator. ← HUMAN GATE (if MEDIUM findings exist)
  7. Commit: git commit -m "feat: <description>" # output: commit_sha

Phase 4: REVIEW

  1. Run full test suite. # output: test_results (PASS|FAIL)
  2. If FAIL: diagnose, fix, re-run. Loop max 3x before escalating to Operator.
  3. Run code-quality on full diff. # output: quality_report
  4. Run drift-detect on changed files. # output: drift_findings
  5. All LOW certainty findings → Operator review. ← HUMAN GATE
  6. Confirm ready to ship. ← HUMAN GATE

Phase 5: SHIP

  1. Push branch: git push -u origin <branch> # output: remote_branch
  2. Create PR: gh pr create --title "<task>" --body "<plan_summary>" # output: pr_url
  3. Monitor CI: poll gh run list --branch <branch> every 30s. # output: ci_status
  4. If CI fails: check logs gh run view --log-failed, diagnose, fix, push. Max 2 retries.
  5. If CI passes: request merge or auto-merge if authorized. # output: merge_sha
  6. Cleanup: delete branch after merge. # output: DONE

State & Resumability

State encoded in git:

  • Current phase → branch name prefix (task/<id>-<slug>)
  • Plan → first commit message body
  • Quality report → .b00t/quality-report.md (gitignored, ephemeral)
  • CI status → gh run list output

Resume interrupted task:

/next-task --resume <branch_name>

Detects current phase from branch + commit state, continues from last gate.

Flags

/next-task                    # Auto-discover next task
/next-task --task <id>        # Specific task by id
/next-task --resume <branch>  # Resume interrupted pipeline
/next-task --phase <phase>    # Start from specific phase
/next-task --skip-gates       # ⚠️ Skip human gates (CI/CD use only)

Gate Summary

GateTriggerRequired
Task confirmationAfter DISCOVERAlways
Plan approvalAfter PLANAlways
MEDIUM quality findingsDuring IMPLEMENTIf MEDIUM findings exist
LOW quality findingsDuring REVIEWIf LOW findings exist
Ship confirmationBefore SHIPAlways (unless --skip-gates)

Integration

  • Uses certainty-grade skill for all findings
  • Uses code-quality skill at IMPLEMENT and REVIEW phases
  • Uses certainty-grade skill for all findings
  • Uses code-quality + deslop skills at IMPLEMENT phase
  • Uses drift-detect at REVIEW phase
  • Uses model-routing skill to select model per phase
  • Uses b00t learn for task-relevant topics before IMPLEMENT
  • Uses taskmaster-ai MCP when available
  • Falls back to gh issues if taskmaster-ai unavailable

Sponsors

Details

Marketplace
elasticdotventures/_b00t_
Source
plugins/next-task
Category
Community

More from elasticdotventures/_b00t_

All 3