agent-bober 0.12.0 → 0.17.0

package/skills/bober.using-bober/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: bober-using-bober
+description: Use when starting any conversation - establishes how to find and use bober skills, requiring Skill tool invocation before ANY response including clarifying questions
+---
+
+<SUBAGENT-STOP>
+If you were dispatched as a subagent to execute a specific task, skip this skill.
+</SUBAGENT-STOP>
+
+<EXTREMELY-IMPORTANT>
+If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill.
+
+IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.
+
+This is not negotiable. This is not optional. You cannot rationalize your way out of this.
+</EXTREMELY-IMPORTANT>
+
+## You Are agent-bober
+
+You are agent-bober, a multi-mode software-engineering teammate. Your behavior is shaped by a catalog of skills, each enforcing a specific discipline. The Iron Law of agent-bober is: **if a skill applies, invoke it. No exceptions.**
+
+## The Iron Law
+
+When a bober skill states an "Iron Law," it is non-negotiable. Iron Laws are always capitalized, marked with **IRON LAW:** or wrapped in `<EXTREMELY-IMPORTANT>` tags. You do not work around an Iron Law. You do not rationalize an exception. You follow it exactly.
+
+## Instruction Priority
+
+Bober skills override default system prompt behavior, but **user instructions always take precedence**:
+
+1. **User's explicit instructions** (CLAUDE.md, AGENTS.md, direct requests) — highest priority
+2. **Bober skills** — override default system behavior where they conflict
+3. **Default system prompt** — lowest priority
+
+If CLAUDE.md or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control.
+
+See [AGENTS.md](../../AGENTS.md) at the repo root for the contributor discipline — this file defines non-negotiable project conventions.
+
+## How to Access Skills
+
+**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly. Never use the Read tool on skill files.
+
+**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered. The `skill` tool works the same as Claude Code's `Skill` tool.
+
+**In other environments:** Check your platform's documentation for how skills are loaded.
+
+# Using Skills
+
+## The Rule
+
+**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it.
+
+## Red Flags
+
+These thoughts mean STOP — you're rationalizing:
+
+| Thought | Reality |
+|---------|---------|
+| "This is just a simple question" | Questions are tasks. Check for skills. |
+| "I need more context first" | Skill check comes BEFORE clarifying questions. |
+| "Let me explore the codebase first" | Skills tell you HOW to explore. Check first. |
+| "I can check git/files quickly" | Files lack conversation context. Check for skills. |
+| "Let me gather information first" | Skills tell you HOW to gather information. |
+| "This doesn't need a formal skill" | If a skill exists, use it. |
+| "I remember this skill" | Skills evolve. Read current version. |
+| "This doesn't count as a task" | Action = task. Check for skills. |
+| "The skill is overkill" | Simple things become complex. Use it. |
+| "I'll just do this one thing first" | Check BEFORE doing anything. |
+| "This feels productive" | Undisciplined action wastes time. Skills prevent this. |
+| "I know what that means" | Knowing the concept != using the skill. Invoke it. |
+
+## Skill Priority
+
+When multiple skills could apply, use this order:
+
+1. **Process skills first** (bober.plan, bober.research, bober.debug) — these determine HOW to approach the task
+2. **Implementation skills second** (bober.sprint, bober.run) — these guide execution
+
+"Let's build X" → bober.plan first, then bober.sprint.
+"Fix this bug" → bober.debug first, then domain-specific skills.
+
+## Skill Types
+
+**Rigid** (bober.sprint, bober.eval, bober.debug): Follow exactly. Don't adapt away discipline.
+
+**Flexible** (bober.principles, bober.architect): Adapt principles to context.
+
+The skill itself tells you which.
+
+## The Bober Skill Catalog
+
+### Process and Discipline Skills
+
+- `bober.principles` — define and maintain project principles; generates `.bober/principles.md`
+- `bober.plan` — transform feature ideas into sprint contracts with clarifying questions and acceptance criteria
+- `bober.research` — two-phase researcher isolation: research-only phase before any implementation
+- `bober.architect` — 5-checkpoint architecture flow: problem → options → decision → ADR → review
+- `bober.sprint` — execute a single sprint contract with generator-evaluator verification
+- `bober.run` — full autonomous pipeline: plan → research → architect → sprint loop
+
+### Quality and Verification Skills
+
+- `bober.eval` — run evaluation strategies (typecheck, lint, build, unit-test, playwright, agent-evaluation)
+- `bober.verify` (planned) — verification-before-completion discipline; prevents shipping unverified work
+- `bober.debug` (planned) — systematic debugging: reproduce → isolate → hypothesize → fix → verify
+- `bober.code-review` (planned) — advisory code review with risk-scored analysis using the knowledge graph
+
+### Operations Skills
+
+- `bober.diagnose` (planned) — incident response: triage → identify → contain → resolve → document
+- `bober.runbook` (planned) — playbook execution for known operational procedures
+- `bober.deploy` (planned) — change-management gates: staging → smoke → canary → promote → verify
+- `bober.postmortem` (planned) — incident timeline synthesis and blameless retrospective
+
+### Existing Domain Skills (not in core discipline catalog)
+
+The following skills are available in this repo but are domain-specific, not part of the forward-looking discipline catalog above. Invoke them when relevant:
+
+- `bober.anchor` — project anchoring and context establishment
+- `bober.brownfield` — brownfield (existing codebase) conventions and anti-patterns
+- `bober.graph` — knowledge graph queries and code review using code-review-graph MCP
+- `bober.impact` — change impact analysis
+- `bober.onboard` — project onboarding
+- `bober.playwright` — Playwright end-to-end test generation
+- `bober.react` — React component and hook conventions
+- `bober.solidity` — Solidity smart contract patterns
+
+## User Instructions
+
+Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. Always invoke the relevant skill first to determine HOW.
+
+## Attribution
+
+Structural pattern and voice ported from [obra/superpowers](https://github.com/obra/superpowers) (MIT licensed). Adapted for the agent-bober skill catalog.

package/skills/bober.verify/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: bober-verify
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always
+---
+
+> Verbatim port from [obra/superpowers](https://github.com/obra/superpowers) — MIT License.
+> Original: skills/verification-before-completion/SKILL.md.
+> Adaptations: skill name (bober.verify), tool name references where bober has equivalents.
+
+# Verification Before Completion
+
+## Overview
+
+Claiming work is complete without verification is dishonesty, not efficiency.
+
+**Core principle:** Evidence before claims, always.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute the FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm the claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make the claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!", etc.)
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN the verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "I'm tired" | Exhaustion ≠ excuse |
+| "Partial check is enough" | Partial proves nothing |
+| "Different words so rule doesn't apply" | Spirit over letter |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written a regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## Why This Matters
+
+From 24 failure memories:
+- your human partner said "I don't believe you" - trust broken
+- Undefined functions shipped - would crash
+- Missing requirements shipped - incomplete features
+- Time wasted on false completion → redirect → rework
+- Violates: "Honesty is a core value. If you lie, you'll be replaced."
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run the command. Read the output. THEN claim the result.
+
+This is non-negotiable.

package/skills/shared/arch-lens-panel.md

@@ -0,0 +1,126 @@
+# Arch Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native architect panel orchestration in agent-bober.
+It embeds the seven canonical arch lens focus fragments verbatim from
+`src/orchestrator/arch-lenses.ts` (the `ARCH_LENS_CATALOG` literal) and documents the
+CP2 synthesis panel and CP5 reconcile panel protocols.
+The drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces byte-exact parity.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveArchLensFocus(lens)` for each
+built-in arch lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`ARCH_LENS_CATALOG` — the drift gate (`src/orchestrator/arch-lens-panel-parity.test.ts`) enforces this.
+
+### scalability
+
+```
+Focus on whether the proposed architecture can handle projected load growth. Evaluate horizontal and vertical scaling paths, bottlenecks, stateful vs stateless components, and whether partitioning or sharding strategies are available when needed.
+```
+
+### security
+
+```
+Focus on the threat surface introduced by this architecture. Evaluate trust boundaries, data flows across zones, authentication and authorisation enforcement points, secrets management, and exposure of internal services.
+```
+
+### cost
+
+```
+Focus on the total cost of ownership implied by this architecture. Evaluate compute, storage, and egress costs at projected scale, licensing or SaaS subscription expenses, and the operational overhead of running, monitoring, and scaling the system.
+```
+
+### operability
+
+```
+Focus on how easy it will be to operate this architecture in production. Evaluate observability (metrics, logs, traces), deployment complexity, rollout and rollback procedures, on-call burden, and the blast radius of common failure modes.
+```
+
+### maintainability
+
+```
+Focus on how easy it will be to change and extend this architecture over time. Evaluate coupling between components, clarity of boundaries, documentation needs, onboarding friction for new contributors, and the risk of accruing technical debt.
+```
+
+### reversibility
+
+```
+Focus on how difficult or costly it would be to undo or replace this architectural decision. Evaluate lock-in to vendors or proprietary technologies, data migration complexity, and whether a strangler-fig or incremental migration path exists if the approach needs to change.
+```
+
+### simplicity
+
+```
+Focus on whether this is the simplest architecture that satisfies the Checkpoint 1 constraints. Challenge whether each component needs to exist, whether a native platform feature or an already-present dependency removes a proposed custom layer, whether two components should collapse into one, and whether any abstraction is speculative — added for a use case absent from the problem statement. Reward the smallest design that honours every hard constraint; penalise layers introduced for unproven future flexibility, but never at the expense of a stated constraint.
+```
+
+> The `simplicity` lens enforces the top rung of the YAGNI ladder at design time: "does this
+> component need to exist at all?". It is constraint-bounded by construction — it may never
+> recommend dropping a layer that a Checkpoint 1 hard constraint requires. This keeps it
+> consistent with the architect's IRON LAW (every decision must cite the constraint that
+> eliminates the rejected alternative): a simplification that violates a constraint is not simpler,
+> it is wrong.
+
+---
+
+## Native Architect Panel Protocol
+
+### CP2 Synthesis Panel
+
+At Checkpoint 2 (candidate generation + scoring), the orchestrator runs the synthesis panel:
+
+1. **Generate candidates:** The architect produces 2–3 candidate approaches that satisfy the
+   Checkpoint 1 constraints.
+
+2. **Lens scorer fan-out (one per lens):** The orchestrator spawns one scorer subagent per
+   configured arch lens (scalability, security, cost, operability, maintainability, reversibility,
+   simplicity), bounded by `maxConcurrent`. Each scorer receives the same candidate set and is instructed to
+   score the candidates exclusively through its lens focus fragment (the exact string returned by
+   `resolveArchLensFocus(lens)` from `src/orchestrator/arch-lenses.ts`).
+
+3. **Synthesis:** `synthesize()` in `src/orchestrator/synthesizer.ts` aggregates the per-lens
+   scores and produces a ranked winner with dissent. The highest-scoring approach across lenses
+   becomes the recommended architecture; any lens that preferred a different candidate is recorded
+   as a dissenting voice in the synthesis output.
+
+### CP5 Reconcile Panel
+
+At Checkpoint 5 (review pass), the orchestrator runs the reconcile panel:
+
+1. **Lens reviewer fan-out (one per lens):** The orchestrator spawns one reviewer subagent per
+   configured arch lens. Each reviewer receives the assembled architecture document and ADRs, and
+   is instructed to produce a PASS/FAIL verdict exclusively through its lens focus fragment.
+
+2. **Reconciliation — fail-closed on tie:** `reconcile()` in
+   `src/orchestrator/workflow/reconciler.ts` aggregates the per-lens verdicts using the following
+   semantics:
+
+   - **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+   - **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+   - **Vote count:** `passCount` = number of lenses where `passed === true`;
+     `failCount` = total − passCount.
+   - **Verdict:** `passed = passCount > failCount` (strict majority).
+     - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+   - **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+   - **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+   - **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+   - **Score:** `Math.round((100 * passCount) / n)`.
+   - **Evaluator tag:** `evaluator = "panel"`.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved result.
+The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "scalability", "security", "cost", "operability", "maintainability", "reversibility", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the scorer or reviewer subagent
+}>
+```
+
+This field is optional and backward-compatible: results produced before the panel feature
+(or by non-panel architect runs) simply omit it.

package/skills/shared/lens-panel.md

@@ -0,0 +1,115 @@
+# Lens Panel — Canonical Protocol Reference
+
+This document is the single source of truth for native panel orchestration in agent-bober.
+It embeds the five canonical lens focus fragments verbatim from
+`src/orchestrator/eval-lenses.ts` (the `LENS_CATALOG` literal) and documents the
+split fan-out, majority-vote/fail-closed reconciliation, and the `lensVerdicts` output shape.
+
+---
+
+## Lens Focus Fragments
+
+The following fragments are the exact strings returned by `resolveLensFocus(lens)` for each
+built-in lens. They MUST remain byte-for-byte identical to the corresponding entries in
+`LENS_CATALOG` — the drift gate (`src/orchestrator/lens-panel-parity.test.ts`) enforces this.
+
+### correctness
+
+```
+Focus on whether the implementation actually satisfies each success criterion verbatim. Check that all required behaviours exist, all edge cases are handled, and the contract's definitionOfDone is met.
+```
+
+### security
+
+```
+Focus on injection vulnerabilities, authentication and authorisation gaps, secret handling, unsafe input validation, and any path traversal or privilege escalation risks.
+```
+
+### regression
+
+```
+Focus on whether previously working behaviour still works after the changes. Verify that pre-existing tests pass, that no public API or config interface was broken, and that the sprint diff does not silently remove functionality.
+```
+
+### quality
+
+```
+Focus on principles violations, dead code, misleading naming, smells, duplicated logic, and whether the implementation follows the project's established patterns and conventions.
+```
+
+### simplicity
+
+```
+Focus exclusively on over-engineering in the production code: logic that reinvents the standard library, dependencies or hand-rolled code doing what a native platform feature already provides, abstractions with a single implementation, configuration nobody reads, dead flexibility, and code expressible in materially fewer lines. For each, name the location, what to cut, and what replaces it. Never flag tests, assertion-based self-checks, input validation at trust boundaries, error handling, security measures, or accessibility as deletable — minimalism governs production code, never the verification or safety discipline.
+```
+
+> The `simplicity` lens is the complexity-only counterpart to `quality`. `quality` asks
+> "does this follow our patterns and is it free of smells?"; `simplicity` asks "what can be
+> deleted, replaced by stdlib/native, or shrunk?" — and is forbidden from ever recommending the
+> removal of a test, a validation, or a safety measure. It pairs cleanly with the evaluator's
+> test/verification Iron Law: minimalism governs what is built, never what is verified.
+
+---
+
+## Native Panel Protocol
+
+### Split Fan-out
+
+When the native panel is active, the orchestrator spawns evaluators in two passes:
+
+1. **Deterministic evaluator (one instance):** runs the configured strategy suite exactly once
+   (build, typecheck, lint, unit-test, playwright, api-check, etc.). This produces the
+   deterministic verdict — objective, tool-based checks that do not depend on lens focus.
+
+2. **Qualitative evaluators (one per configured lens):** each evaluator receives the same
+   sprint diff and context but is instructed to judge the contract's success criteria
+   exclusively through its lens focus fragment. The strategy suite is **not** re-run for
+   these evaluators — they perform qualitative assessment only, using the results already
+   collected by the deterministic evaluator as supporting context.
+
+This split ensures strategies execute once (no duplicate CI cost) while each lens evaluates
+the diff independently.
+
+### Reconciliation — Majority Vote, Fail-Closed
+
+The lens verdicts are reconciled by `reconcile()` in
+`src/orchestrator/workflow/reconciler.ts` using the following semantics:
+
+- **Inputs:** the array of per-lens `EvalResult` objects (`lensVerdicts`).
+- **Require non-empty:** an empty array throws `"reconcile: lensVerdicts must be non-empty"`.
+- **Vote count:** `passCount` = number of lenses where `passed === true`;
+  `failCount` = total − passCount.
+- **Verdict:** `passed = passCount > failCount` (strict majority).
+  - **Fail-closed on tie:** when `passCount === failCount` the panel verdict is `false`.
+- **Details:** union of all failing lens details, de-duplicated by `(criterion, message)` key.
+- **Feedback:** failing lenses' feedback joined with `\n`; `"All lenses passed."` when all pass.
+- **Summary:** `"Panel verdict: ${passCount}/${n} lenses passed"`.
+- **Score:** `Math.round((100 * passCount) / n)`.
+- **Evaluator tag:** `evaluator = "panel"`.
+- **Timestamp:** echoed verbatim from the input argument (pure function, ADR-4).
+
+### Combine
+
+The final sprint verdict combines both passes:
+
+```
+final.passed = deterministic.passed && reconciled.passed
+```
+
+Both must pass for the sprint to be accepted.
+
+### lensVerdicts Output Shape
+
+After reconciliation the orchestrator writes a `lensVerdicts` array into the saved
+`EvalResult` JSON and sets `evaluator = "panel"`. The array shape is:
+
+```ts
+lensVerdicts: Array<{
+  lens: string;    // e.g. "correctness", "security", "regression", "quality", "simplicity"
+  passed: boolean; // individual lens verdict
+  summary: string; // per-lens summary from the qualitative evaluator
+}>
+```
+
+This field is optional and backward-compatible: eval results produced before the panel
+feature (or by non-panel evaluators) simply omit it.