buildanything 1.6.0 → 1.7.1

package/commands/protocols/eval-harness.md

@@ -1,62 +0,0 @@
-# Eval Harness Protocol
-
-You are the orchestrator. Phase 6.1 audits are complete. Before running the metric loop, define formal eval cases that are concrete, executable, and reproducible. This replaces subjective narrative audits with deterministic pass/fail tests.
-
-## How This Differs from the Metric Loop
-
-The metric loop answers "how good is this?" (qualitative score 0-100, iterative improvement).
-The eval harness answers "does this specific behavior work reliably?" (binary pass/fail, deterministic).
-
-They are complementary: eval harness failures become specific issues for the metric loop to fix.
-
-## Step 0: Define Eval Cases
-
-YOU (the orchestrator) define eval cases based on:
-- Audit findings from Phase 6.1 (highest-severity items first)
-- Architecture doc (API contracts, auth model, data validation rules)
-- Design doc (core user flows, edge cases)
-
-Write eval cases to `docs/plans/.build-state.md` under `## Eval Harness`:
-
-| # | Name | Action | Expected Result | pass@k | Severity |
-|---|------|--------|-----------------|--------|----------|
-
-**Severity thresholds (non-negotiable):**
-- CRITICAL: pass@5 (must pass 5/5 — 100% reliability)
-- HIGH: pass@4 (must pass 4/5 — 80% reliability)
-- MEDIUM: pass@3 (must pass 3/5 — 60% reliability)
-
-Aim for 8-15 eval cases. Cover: auth boundaries, input validation, error handling, core happy path, primary edge cases.
-
-**Eval cases must be concrete and executable** — actual commands (curl, function calls, UI interactions), not descriptions. Bad: "Auth should work." Good: "curl -X GET /api/recipes without Authorization header → expect 401."
-
-## Step 1: Run Eval
-
-Call the Agent tool — description: "Run eval harness" — mode: "bypassPermissions" — prompt:
-
-"[COMPLEXITY: M] Run these eval cases. For each case, execute the action the specified number of times (k). Report per case: PASS (N/k passed, meets threshold) or FAIL (N/k passed, below threshold). Include the actual result on failures. [paste eval case table]"
-
-<HARD-GATE>
-The eval agent RUNS cases. It does NOT define them. Case definition is the orchestrator's job.
-</HARD-GATE>
-
-## Step 2: Score
-
-Count PASS cases / total cases. This is the eval baseline. Record to `docs/plans/.build-state.md`.
-
-## Step 3: Feed into Metric Loop
-
-Any FAIL case with severity CRITICAL or HIGH becomes a candidate issue for the Phase 6.2 metric loop. Pass the failure details (case name, action, expected vs actual) as context when defining the metric loop's metric.
-
-## Step 4: Re-evaluate After Metric Loop
-
-After the Phase 6.2 metric loop exits, re-run the eval harness. All CRITICAL cases must now pass. If any CRITICAL case still fails, flag it for the Reality Checker in Step 6.3.
-
----
-
-## Rules
-
-- Eval cases are defined by the ORCHESTRATOR, not by the eval agent.
-- pass@k thresholds are non-negotiable per severity level.
-- Re-run eval after metric loop to verify fixes — this is the exit gate.
-- Eval failures feed into the metric loop as specific, concrete issues — not vague audit findings.

package/commands/protocols/metric-loop.md

@@ -1,94 +0,0 @@
-# Metric Loop Protocol
-
-You are the orchestrator. You are about to run a metric-driven iteration loop on an artifact (code, architecture, docs, etc.) to drive it toward a quality target.
-
-## Step 0: Define Your Metric
-
-Before iterating, YOU define the metric for this specific context. Consider:
-- What is the artifact? (a task implementation, a security audit, an architecture doc, etc.)
-- What does "good" look like? (all tests pass, zero critical vulns, all acceptance criteria met, etc.)
-- Is the metric quantitative (test pass rate, vuln count, coverage %) or qualitative (architecture completeness, doc clarity)?
-
-Write a **Metric Definition** block to `docs/plans/.build-state.md`:
-
-```
-## Active Metric Loop
-Phase: [current phase]
-Artifact: [what you're iterating on]
-Metric: [what you're measuring, in one sentence]
-How to measure: [what the measurement agent should do — run tests, audit code, check criteria, etc.]
-Target: [score 0-100 at which you stop]
-Max iterations: [hard cap, default 5]
-```
-
-Then create a score log table:
-
-```
-| Iter | Score | Delta | Top Issue | Files |
-|------|-------|-------|-----------|-------|
-```
-
-When starting a new metric loop, REPLACE the previous Active Metric Loop section (if any). There is only ever ONE active metric loop. Previous loop results should already be recorded in their phase's section above. When the loop completes (Step 2 exit), rename the section header from `## Active Metric Loop` to `## Completed Metric Loop — [Phase N]` and leave it for historical reference.
-
-If you are in Phase 5, also record the current sub-step for the overall task cycle (not all of these are within the metric loop itself):
-```
-Sub-step: [5.1 Implement | 5.1b Cleanup | 5.2 Metric Loop | 5.3 Loop Exit | 5.4 Verify]
-```
-This tells the orchestrator exactly where to resume after context compaction.
-
-## Step 1: MEASURE
-
-Call the Agent tool — description: "Measure [metric]" — prompt:
-
-"[How to measure, from your metric definition]. Score the current state 0-100. Return your response with a clear SCORE: [number] line, a list of FINDINGS, and the single TOP ISSUE most likely to improve the score if fixed."
-
-Read the agent's response. You need: the SCORE, the TOP ISSUE, and the file paths for diagnosis in Step 3. Record the score to `docs/plans/.build-state.md`. The full findings list is useful for diagnosis but does NOT need to persist in your context across iterations — once you've picked the top issue, the details of lower-priority findings can go. Append a row to the score log in `docs/plans/.build-state.md`:
-
-| Iter | Score | Delta | Top Issue | Files |
-|------|-------|-------|-----------|-------|
-
-## Step 2: CHECK EXIT
-
-Stop the loop if ANY of these:
-
-- **Score >= target** → done. Log "Target met at iteration [N]."
-- **Iteration >= max** → done. Log "Max iterations reached. Final score: [N]."
-- **Stall: last 2 scores show no improvement** (delta <= 0 twice in a row) → done. Log "Stalled at score [N]."
-
-On stall or max iterations:
-- **Interactive mode:** present score history + top remaining issue to user. Ask for direction.
-- **Autonomous mode:** if score >= 60% of target, accept with warning. Otherwise skip. Log to `docs/plans/build-log.md`.
-
-If not exiting, continue to Step 3.
-
-## Step 3: DIAGNOSE
-
-Look at the findings from Step 1. Pick the ONE highest-impact issue — the single fix most likely to move the score. Do not try to fix everything at once. This is the autoresearch insight: one targeted change per iteration, measured impact.
-
-## Step 4: IMPROVE
-
-Call the Agent tool — description: "Fix [top issue]" — mode: "bypassPermissions" — prompt:
-
-"TARGETED FIX: [specific issue to fix, from diagnosis]. CONTEXT: [relevant architecture/criteria]. Make this specific change. Do not refactor unrelated code. Commit: 'fix: [description]'."
-
-> **Do NOT pass the measurement agent's full findings to this agent. Only pass the single diagnosed issue and relevant file paths.**
-
-## Step 5: LOOP
-
-Return to Step 1. Re-measure the artifact after the fix.
-
----
-
-## Rules
-
-<HARD-GATE>
-AUTHOR-BIAS ELIMINATION: The measurement agent and the fix agent must NEVER share context.
-- They MUST be separate Agent tool calls (separate subprocesses, separate context windows).
-- The fix agent receives ONLY: (a) the single top issue diagnosed in Step 3, (b) the relevant file paths, (c) the acceptance criteria. It does NOT receive the measurement agent's full findings, score breakdown, or other issues.
-- The measurement agent in the next iteration does NOT know what the fix agent did — it measures the artifact fresh.
-- Rationale: When a reviewer shares context with an implementer, the implementer unconsciously optimizes for the reviewer's framing rather than actual quality.
-</HARD-GATE>
-- One fix per iteration. Measure its impact before fixing the next thing.
-- Track ALL scores in `docs/plans/.build-state.md` so the history survives context compaction.
-- If context was compacted mid-loop: read `docs/plans/.build-state.md`, find the Active Metric Loop section, resume from the last recorded iteration.
-- CONTEXT HYGIENE: Measurement agents are analysis agents — read their full output for diagnosis. But once you've picked the top issue (Step 3) and dispatched the fix (Step 4), the detailed findings from THAT iteration are spent. Don't accumulate findings across iterations — each measurement is fresh.

package/commands/protocols/planning.md

@@ -1,56 +0,0 @@
-# Planning Protocol
-
-You are the orchestrator converting a validated Design Document and Architecture Document into an ordered, developer-ready task list.
-
-## Input
-
-You need two documents before running this protocol:
-- **Design Document** (`docs/plans/YYYY-MM-DD-[topic]-design.md`) — scope, user flows, data model, tech stack
-- **Architecture Document** (`docs/plans/architecture.md`) — services, API contracts, database schema, component tree
-
-## Step 1: Break Down
-
-Decompose the architecture into ordered, atomic tasks. Each task must be:
-
-- **Implementable independently** — a developer agent can build it without needing unfinished work from other tasks
-- **Testable** — there are concrete acceptance criteria that can be verified
-- **Scoped to MVP** — if the design doc says a feature is deferred, do not create tasks for it
-
-For each task:
-
-```
-### Task [N]: [name]
-**Type:** frontend / backend / integration / infrastructure
-**Description:** [what to build, 2-3 sentences]
-**Acceptance Criteria:**
-- [ ] [specific, verifiable criterion]
-- [ ] [specific, verifiable criterion]
-**Dependencies:** [task numbers that must complete first, or "none"]
-**Size:** S (< 1 hour) / M (1-3 hours) / L (3+ hours)
-```
-
-## Step 2: Order
-
-Order tasks by dependency chain, then by priority within each dependency level:
-
-1. Infrastructure/scaffolding first (project setup, database schema, base config)
-2. Core data model and API endpoints
-3. Primary user flow (the main thing the user does)
-4. Supporting features
-5. Polish, error handling, edge cases
-
-Flag any circular dependencies — these indicate an architecture problem that needs resolution before building.
-
-## Step 3: Validate
-
-Check the task list against the design doc:
-
-- Every feature in MVP scope has at least one task
-- No task exceeds the MVP boundary
-- No task is too large (L tasks should be split if possible)
-- Dependency chains are no deeper than 3 levels
-- Acceptance criteria are specific enough that a developer agent can verify them without ambiguity
-
-## Step 4: Save
-
-Save to `docs/plans/sprint-tasks.md`.

package/commands/protocols/verify.md

@@ -1,63 +0,0 @@
-# Verification Protocol
-
-You are the orchestrator. You are about to run a deterministic verification gate — a fast, sequential pass/fail check that catches regressions before expensive audit agents run.
-
-## When to Run
-
-Run this protocol at every phase boundary: after scaffolding, after each task, before final review. It is cheap. Run it often.
-
-## Step 1: Detect Stack
-
-Before running checks, detect the project's stack from manifest files:
-
-| Manifest | Stack | Build | Types | Lint | Test | Security |
-|----------|-------|-------|-------|------|------|----------|
-| `package.json` | Node | `npm run build` | `npx tsc --noEmit` | `npm run lint` | `npm test` | `npm audit` |
-| `requirements.txt` / `pyproject.toml` | Python | — | `mypy .` | `ruff check .` | `pytest` | `pip audit` |
-| `go.mod` | Go | `go build ./...` | (included in build) | `golangci-lint run` | `go test ./...` | `govulncheck ./...` |
-| `Cargo.toml` | Rust | `cargo build` | (included in build) | `cargo clippy` | `cargo test` | `cargo audit` |
-
-Skip any check that does not apply (e.g., skip Build for a pure Python script, skip Type-Check for JavaScript without TypeScript). A skipped check counts as PASS.
-
-## Step 2: Run Checks Sequentially
-
-Call the Agent tool — description: "Verify [phase name]" — mode: "bypassPermissions" — prompt:
-
-"Run the Verification Protocol. Execute all 6 checks sequentially, stop on first failure. Report: VERIFY: PASS (6/6) or VERIFY: FAIL at step [N] — [check name]: [reason]."
-
-The agent runs these checks in order, stopping on the first FAIL:
-
-| # | Check | What it does |
-|---|-------|-------------|
-| 1 | Build | Project compiles/bundles without errors |
-| 2 | Type-Check | No type errors (tsc, mypy, etc.) |
-| 3 | Lint | No lint violations |
-| 4 | Test | All tests pass |
-| 5 | Security | No known vulnerabilities in deps |
-| 6 | Diff Review | `git diff` of uncommitted changes — no debug code, no secrets, no obvious regressions |
-
-<HARD-GATE>
-ONE AGENT, ONE PASS: The orchestrator spawns exactly ONE agent for the entire verification. This is a single Agent tool call, not 6 separate agents. The agent runs each check as a sequential shell command and evaluates the result before proceeding.
-</HARD-GATE>
-
-## Step 3: Handle Result
-
-**On PASS:** Log `VERIFY: PASS (6/6)` to `docs/plans/.build-state.md`. Proceed to next phase.
-
-**On FAIL:** Read the failure reason and spawn a targeted fix agent:
-
-| Failed Check | Fix Strategy |
-|-------------|-------------|
-| Build / Type-Check / Lint | Run the Build-Fix Protocol (`commands/protocols/build-fix.md`). It isolates the first error, fixes it, rebuilds, detects cascade resolution, and reverts bad fixes automatically. |
-| Test | Spawn fix agent: "Fix the failing test: [test name]. Read the test, read the implementation, fix the implementation — not the test — unless the test is wrong." |
-| Security | Spawn fix agent: "Resolve vulnerability: [advisory]. Update the dependency or apply the recommended remediation." |
-| Diff Review | Spawn fix agent: "Remove debug code / hardcoded secrets / regressions found in diff review: [details]." |
-
-After the fix agent completes, re-run verification from Step 2.
-
-<HARD-GATE>
-MAX 3 FIX ATTEMPTS: If verification fails 3 times on the same phase:
-- **Interactive mode:** present the failure history to the user. Ask for direction.
-- **Autonomous mode:** log the failure to `docs/plans/build-log.md` and proceed with a warning.
-Do not loop forever.
-</HARD-GATE>