agent-bober 0.11.6 → 0.15.0

package/skills/bober.sprint/SKILL.md

@@ -30,9 +30,13 @@ Also read `.bober/principles.md` if it exists. You will include the principles t
 
 ## Step 1: Identify the Target Sprint
 
-**Find the active PlanSpec.** List all specs in `.bober/specs/`. For each spec, read only the **first 5 lines** — the `status` field is near the top. Skip any spec where `status` is `"completed"`. From the remaining specs, pick the most recent one (sort by `createdAt` descending).
+**Find the active PlanSpec.** List all specs in `.bober/specs/`. For each spec, read only the **first 10 lines** — the `status` field is near the top. Apply this triage:
 
-If all specs are `completed` and no sprint number was provided, tell the user all plans are complete.
+- `"completed"` or `"abandoned"` → skip entirely.
+- `"needs-clarification"` → BLOCK this spec from sprint execution. Print the open `clarificationQuestions` from the spec and tell the user to resolve via `npx agent-bober plan answer <specId>` (interactive) or `npx agent-bober plan answer <specId> <questionId> "<answer>"` (one-shot). Do NOT spawn the generator. Do NOT pick this spec as the active one. If it's the only spec, exit.
+- `"draft"`, `"ready"`, `"in-progress"` → eligible. From the eligible specs, pick the most recent one (sort by `createdAt` descending).
+
+If all specs are `completed`/`abandoned` and no sprint number was provided, tell the user all plans are complete. If the only remaining spec is `needs-clarification`, exit with the clarification message.
 
 **If a sprint number was provided as an argument:**
 - Find the contract for that sprint number: `.bober/contracts/sprint-<specId>-<N>.json`
@@ -463,260 +467,3 @@ Read `pipeline.contextReset` from config:
 After completing this phase, suggest the following next steps to the user:
 - `/bober-eval` — Evaluate the current sprint output independently
 - `/bober-sprint` — Execute the next sprint in the plan
-
-
----
-
-<!-- Reference: contract-schema.md -->
-
-# SprintContract JSON Schema
-
-This document defines the complete schema for SprintContract documents. Sprint contracts are the binding agreement between the Planner, Generator, and Evaluator for a single sprint.
-
-## Location
-
-SprintContract files are stored at: `.bober/contracts/<contractId>.json`
-
-## Naming Convention
-
-- `contractId` format: `sprint-<specId>-<sprint-number>`
-- Example: `sprint-spec-20260326-user-auth-1`
-- Sprint numbers are 1-indexed (first sprint is 1, not 0)
-
-## Full Schema
-
-```json
-{
-  "contractId": "string (required)",
-  "specId": "string (required, references parent PlanSpec)",
-  "sprintNumber": "number (required, 1-indexed)",
-  "title": "string (required, concise sprint title)",
-  "description": "string (required, what this sprint delivers)",
-  "status": "string (required, one of: proposed, in-progress, completed, needs-rework)",
-  "createdAt": "string (required, ISO-8601)",
-  "updatedAt": "string (required, ISO-8601)",
-  "completedAt": "string (optional, ISO-8601, set when status becomes completed)",
-
-  "dependsOn": [
-    "string — contractId references for sprints that must complete before this one"
-  ],
-
-  "features": [
-    "string — featureId references from the parent PlanSpec"
-  ],
-
-  "successCriteria": [
-    {
-      "criterionId": "string (required, format: sc-<sprint>-<index>)",
-      "description": "string (required, specific testable criterion)",
-      "verificationMethod": "string (required, one of: manual, typecheck, lint, unit-test, playwright, api-check, build, custom)",
-      "required": "boolean (required, true = must pass for sprint to pass)",
-      "customCommand": "string (optional, command to run for custom verification)"
-    }
-  ],
-
-  "generatorNotes": "string (required, guidance for the Generator agent)",
-  "evaluatorNotes": "string (required, guidance for the Evaluator agent)",
-
-  "estimatedFiles": [
-    "string — file paths expected to be created or modified"
-  ],
-
-  "estimatedDuration": "string (required, one of: small, medium, large)",
-
-  "iterationHistory": [
-    {
-      "iteration": "number",
-      "evalId": "string — reference to EvalResult",
-      "result": "string (pass | fail)",
-      "timestamp": "string (ISO-8601)"
-    }
-  ],
-
-  "lastEvalId": "string (optional, reference to most recent EvalResult)"
-}
-```
-
-## Field Descriptions
-
-### Core Fields
-
-| Field | Description |
-|-------|-------------|
-| `contractId` | Unique identifier. Generated by the Planner. Never changes. |
-| `specId` | Reference to the parent PlanSpec. Used to load broader context. |
-| `sprintNumber` | Position in the sprint sequence. 1-indexed. |
-| `title` | Concise description of what this sprint delivers. Should start with a verb: "Implement...", "Add...", "Create...". |
-| `description` | 2-4 sentences describing the sprint's deliverables and scope. |
-| `status` | Lifecycle state. See Status Transitions below. |
-
-### Status Transitions
-
-```
-proposed → in-progress → completed
-                ↓
-          needs-rework → in-progress → completed
-```
-
-- `proposed`: Created by the Planner. Not yet started or reviewed.
-- `in-progress`: Contract negotiated and Generator is working on it.
-- `completed`: All required success criteria passed evaluation.
-- `needs-rework`: Failed evaluation after maximum iterations. Requires human intervention or plan revision.
-
-### Dependencies
-
-| Field | Description |
-|-------|-------------|
-| `dependsOn` | Array of `contractId` values that must have status `completed` before this sprint can start. Empty array for the first sprint. |
-| `features` | Array of `featureId` values from the parent PlanSpec that this sprint implements (partially or fully). |
-
-### Success Criteria
-
-Each success criterion is a single testable statement that the Evaluator checks independently.
-
-| Field | Description |
-|-------|-------------|
-| `criterionId` | Unique within the contract. Format: `sc-<sprintNumber>-<index>` (1-indexed). |
-| `description` | Specific, testable criterion. Must describe observable behavior or measurable outcome. |
-| `verificationMethod` | How the Evaluator should verify this criterion. |
-| `required` | If `true`, this criterion MUST pass for the sprint to pass. If `false`, it is advisory. |
-| `customCommand` | Only for `verificationMethod: "custom"`. The command the Evaluator should run. |
-
-### Verification Methods
-
-| Method | What the Evaluator Does |
-|--------|------------------------|
-| `manual` | Reads source code and assesses whether the criterion is met based on code inspection and logic tracing. |
-| `typecheck` | Runs the configured typecheck command. Criterion passes if zero type errors. |
-| `lint` | Runs the configured lint command. Criterion passes if zero lint errors (warnings OK). |
-| `unit-test` | Runs the configured test command. Criterion passes if all tests pass. |
-| `playwright` | Runs Playwright E2E tests. Criterion passes if all relevant E2E tests pass. |
-| `api-check` | Tests specific API endpoints using curl or similar. Criterion passes if responses match expectations. |
-| `build` | Runs the configured build command. Criterion passes if build succeeds with exit code 0. |
-| `custom` | Runs `customCommand` and interprets the result. Exit code 0 = pass. |
-
-### Agent Notes
-
-| Field | Description |
-|-------|-------------|
-| `generatorNotes` | Free-form guidance for the Generator. Should include: key files to examine for patterns, known gotchas, suggested implementation order, references to similar existing code. |
-| `evaluatorNotes` | Free-form guidance for the Evaluator. Should include: specific things to test, edge cases to check, how to verify UI criteria, expected API response shapes. |
-
-### Estimates
-
-| Field | Description |
-|-------|-------------|
-| `estimatedFiles` | Array of file paths the Generator is expected to create or modify. This is advisory -- the Generator may touch additional files if needed. The Evaluator uses this to check for unexpected changes. |
-| `estimatedDuration` | Relative size estimate: `small` (30-60 min), `medium` (1-3 hours), `large` (3-5 hours). |
-
-### Iteration History
-
-| Field | Description |
-|-------|-------------|
-| `iterationHistory` | Array of past evaluation attempts. Appended after each evaluation. |
-| `lastEvalId` | Reference to the most recent EvalResult. Updated after each evaluation. |
-
-## Complete Example
-
-```json
-{
-  "contractId": "sprint-spec-20260326-user-auth-1",
-  "specId": "spec-20260326-user-auth",
-  "sprintNumber": 1,
-  "title": "Implement user registration with form and API",
-  "description": "Create the user registration flow end-to-end: a React registration form with email, password, and confirm-password fields; an Express API endpoint that validates input and creates a user record in PostgreSQL with a bcrypt-hashed password; and basic form validation on both client and server.",
-  "status": "proposed",
-  "createdAt": "2026-03-26T10:00:00Z",
-  "updatedAt": "2026-03-26T10:00:00Z",
-  "completedAt": null,
-
-  "dependsOn": [],
-
-  "features": ["feat-1"],
-
-  "successCriteria": [
-    {
-      "criterionId": "sc-1-1",
-      "description": "The project builds successfully with zero errors.",
-      "verificationMethod": "build",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-2",
-      "description": "TypeScript compilation produces zero type errors.",
-      "verificationMethod": "typecheck",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-3",
-      "description": "A registration form component exists at the /register route with email, password, and confirm-password input fields, each with an associated label.",
-      "verificationMethod": "manual",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-4",
-      "description": "POST /api/auth/register accepts { email, password } and returns 201 with { id, email } on success.",
-      "verificationMethod": "api-check",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-5",
-      "description": "POST /api/auth/register returns 400 with an error message when email is already registered.",
-      "verificationMethod": "api-check",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-6",
-      "description": "The password is stored as a bcrypt hash in the database, never in plain text.",
-      "verificationMethod": "manual",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-7",
-      "description": "Client-side validation shows an error when password is shorter than 8 characters before form submission.",
-      "verificationMethod": "manual",
-      "required": true
-    },
-    {
-      "criterionId": "sc-1-8",
-      "description": "ESLint reports zero errors on all new and modified files.",
-      "verificationMethod": "lint",
-      "required": false
-    }
-  ],
-
-  "generatorNotes": "Look at existing route definitions in src/routes/ for the Express routing pattern. The project uses Prisma -- check prisma/schema.prisma for the existing schema and add a User model. Use bcrypt (already in package.json) for password hashing. For the React form, follow the pattern in src/components/ -- the project uses controlled components with useState. The registration form should be at src/pages/Register.tsx and the route added to src/App.tsx.",
-
-  "evaluatorNotes": "For sc-1-3: Read the Register component source and verify it renders three labeled input fields. For sc-1-4 and sc-1-5: Start the dev server and use curl to test the endpoint. For sc-1-6: Read the route handler code and verify bcrypt.hash is called before database insertion. For sc-1-7: Read the form component code and verify client-side validation logic exists for password length.",
-
-  "estimatedFiles": [
-    "prisma/schema.prisma",
-    "src/routes/auth.ts",
-    "src/pages/Register.tsx",
-    "src/App.tsx"
-  ],
-
-  "estimatedDuration": "medium",
-
-  "iterationHistory": [],
-  "lastEvalId": null
-}
-```
-
-## Writing Good Success Criteria
-
-### Do
-
-- Start with an observable action or state: "The form displays...", "The API returns...", "The database contains..."
-- Include specific values: "returns 201", "displays 'Invalid email'", "at least 8 characters"
-- Map each criterion to exactly one verification method
-- Include at least one `build` criterion and one functional criterion per sprint
-- Write criteria the Evaluator can verify without guessing
-
-### Do Not
-
-- Use subjective language: "looks good", "works well", "clean code"
-- Combine multiple checks in one criterion (split them)
-- Reference internal implementation details unless checking them IS the criterion
-- Write criteria that require human visual judgment (unless verification method is `manual` and the check is code-inspectable)
-- Assume the Evaluator has context beyond the contract and handoff documents

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.