@ebrindley/build 0.0.0-stage → 1.42.1-rc28

package/templates/.build-project/task-types/feature.yaml

@@ -0,0 +1,22 @@
+id: feature
+version: 1
+match:
+  priority: 5
+  canonical:
+    category:
+      - execute
+      - test
+    judgeTaskKind:
+      - implementation
+  keywords:
+    - add
+    - implement
+    - build
+    - feature
+    - functionality
+  regex:
+    - \b(create|new)\b.{0,40}\b(feature|endpoint|route|api|page|screen|component|command|workflow|integration|support|capability|enhancement)\b
+policy:
+  executionIntent: edit
+  routing:
+    preferCompetition: false

package/templates/.build-project/task-types/general.yaml

@@ -0,0 +1,4 @@
+id: general
+version: 1
+policy:
+  executionIntent: edit

package/templates/.build-project/task-types/security.yaml

@@ -0,0 +1,38 @@
+id: security
+version: 1
+extends: general
+match:
+  priority: 20
+  keywords:
+    - security
+    - auth
+    - authentication
+    - authorization
+    - token
+    - jwt
+    - oauth
+    - csrf
+    - xss
+    - vuln
+    - vulnerability
+policy:
+  routing:
+    preferCompetition: true
+  decomposition:
+    requiredStageTypes:
+      - verify
+    maxParallelGroups: 1
+    guidance:
+      hints:
+        - Keep allowlists tight and explicit
+        - Add deterministic verify commands (tests/typecheck)
+      antiPatterns:
+        - Do not broaden allowlists to "make it work"
+        - Avoid parallel changes to auth/security surfaces
+  judging:
+    framework: auto
+    defaultScore: 80
+    minimumScore: 70
+  allowlist:
+    requireNonEmpty: true
+    mode: strict

package/templates/AGENTS.template.md

@@ -0,0 +1,85 @@
+# {{PROJECT_NAME}} - AI Agent Guide
+
+> Build config: `.build-project/` | Language: {{LANGUAGE}} | Framework: {{FRAMEWORK}}
+
+<!-- build-usage:begin -->
+## Build
+
+This project uses Build. Run `build context --json` for readiness, branch
+state, and suggested next commands, `build doctor` for setup problems, and
+`build <command> --help` for syntax.
+
+When you are asked to run work through Build, invoke the Build pipeline rather
+than hand-editing managed files or simulating a run yourself. This does not apply
+inside an assigned Build turn (a variant, judge, or synthesis run): there the
+coordinator already runs the pipeline, and you do the assigned task directly in
+the working tree.
+<!-- build-usage:end -->
+
+<!-- build-work-tracking:begin -->
+## Work Tracking
+
+Use Build's backlog, sprint, and task commands as this project's default work
+tracker, regardless of which agent performs the work. Check
+`build plan backlog list` for an existing item before using
+`build plan backlog add`. Use another tracker only when the user explicitly
+requests it or project instructions explicitly designate it. Link implementation
+PRs to the Build item with `build plan backlog link` or `finalize`. If Build is
+unavailable, report that rather than silently switching trackers. Never edit
+managed backlog, sprint, or task files directly. Inside an assigned Build
+turn (a variant, judge, or synthesis run), the coordinator owns tracking: do not
+run backlog, sprint, task, `run`, or `build` commands there. That limits Build
+commands only; still do the assigned task itself (edit files, run the checks it
+names), and if nothing needs to change, say so.
+<!-- build-work-tracking:end -->
+
+## Managed Directories
+
+Never edit these directly. They are owned by the Build CLI.
+
+| Directory  | Purpose                   |
+|------------|---------------------------|
+| `backlog/` | Prioritized work items    |
+| `sprint/`  | Sprint plans and capacity |
+| `task/`    | Task execution artifacts  |
+
+For any operation in a managed directory:
+
+1. Run `build <subcommand> --help` to see available operations.
+2. If a CLI command covers the operation, use it.
+3. If no CLI command covers it, stop and ask. Do not edit the file directly.
+
+```bash
+build plan backlog add "description"
+build plan backlog list
+build plan sprint status
+build plan task list
+```
+
+## Project Context
+
+**Language**: {{LANGUAGE}}
+**Framework**: {{FRAMEWORK}}
+
+Record the target project's real build, test, and contribution instructions
+below. Keep examples specific to this repository rather than copying Build's
+maintainer rules into the consumer project.
+
+Add project-specific guidance below this line.
+
+### Test Commands
+
+```bash
+{{TEST_COMMAND}}
+```
+
+### Build Commands
+
+```bash
+{{BUILD_COMMAND}}
+```
+
+## References
+
+- `.build-project/config/build.config.jsonc` - Project-specific Build config, including its `providers` block
+- `~/.build/config/providers.yaml` - Machine-wide provider registry overrides

package/templates/CLAUDE.template.md

@@ -0,0 +1 @@
+@./AGENTS.md

package/templates/GEMINI.template.md

@@ -0,0 +1 @@
+@./AGENTS.md

package/templates/builtin-workflows/code-review.yaml

@@ -0,0 +1,73 @@
+name: code-review
+description: Cross-provider read-only review — collects diff, runs analysis stage, verifies findings JSON
+# Template variable: baseRef (default HEAD~1).
+# When invoking via 'build review --flywheel', the CLI generates a per-run YAML with the
+# resolved base SHA substituted into the collect-diff command before flywheel run.
+#
+# LOAD-BEARING LITERALS — two exact strings in this file are matched by regexes in
+# src/cli/commands/review.ts. Changing their text or indentation shape breaks the
+# per-run YAML generation for 'build review --flywheel':
+#   1. the collect-diff git diff command  -> substituteCodeReviewCollectDiff
+#   2. the reviewer modelRole line, text AND leading whitespace shape
+#      -> injectReviewerProviderAndModel
+# Both are marked with a LOAD-BEARING comment at their site. Those regexes match the
+# FIRST occurrence in the file, so never repeat either literal in a comment either.
+stages:
+  - id: collect-diff
+    name: Collect Diff
+    type: verify
+    deps: []
+    outputs:
+      "verify-stdout": text
+    verify:
+      commands:
+        # LOAD-BEARING: exact text matched by substituteCodeReviewCollectDiff
+        # (src/cli/commands/review.ts). Do not reword.
+        - git diff --unified=3 HEAD~1...HEAD
+
+  - id: review
+    name: Code Review
+    type: standard
+    deps: [collect-diff]
+    inputs:
+      - collect-diff.verify-stdout
+    promptRef:
+      id: code-review
+    capabilities:
+      modifiesFiles: false
+      executionIntent: analysis
+    # LOAD-BEARING: injectReviewerProviderAndModel (src/cli/commands/review.ts)
+    # matches this line's exact text and leading-whitespace shape to insert
+    # provider/model above it. Do not reword or reindent.
+    modelRole: reviewer
+    outputs:
+      findings: text
+
+  - id: verify-findings
+    name: Verify Findings JSON
+    type: verify
+    deps: [review]
+    inputs:
+      - review.findings
+    # This gate is this workflow's ONLY validation when it runs via
+    # 'build run flywheel run code-review' (nothing downstream parses the artifact),
+    # so it validates against the authoritative contract directly rather than
+    # approximating it: 'internal findings-schema' runs agentOutputSchema from
+    # src/planning/agent-ingest.ts over the artifact, per finding.
+    #
+    # This replaced seven independent 'grep -qzE' whole-buffer scans. Because each
+    # scan was separate, together they proved only that every required field
+    # appeared SOMEWHERE in the artifact — a payload whose fields were spread
+    # across two individually invalid findings passed while agentOutputSchema
+    # rejected both. Being the same schema, this gate cannot drift from
+    # 'build review --flywheel', which Zod-validates the same shape downstream.
+    #
+    # An empty findings array is valid: a clean review must pass.
+    #
+    # 'build' resolved from PATH, NOT 'node dist/entry.js': verify commands run
+    # with the STAGE WORKTREE as cwd, where a repo-relative dist/ path does not
+    # resolve. This mirrors 'build internal review-gate', the existing generated
+    # gate, and is allowlisted by the same validateBuildInternalArgv path.
+    verify:
+      commands:
+        - build internal findings-schema --findings .build-stage-inputs/review.findings.txt

package/templates/builtin-workflows/skills/code-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: code-review
+description: Cross-provider read-only code review — emit structured findings in the agent finding schema
+---
+
+You are performing a read-only code review. You have been given a unified diff artifact to analyze.
+
+## Instructions
+
+1. Read the unified diff provided in the **Input Artifacts** section of your prompt (artifact `collect-diff.verify-stdout` from the collect-diff stage).
+2. Analyze the changes for the following categories:
+   - **correctness** — logic errors, off-by-one errors, incorrect assumptions, broken contracts
+   - **security** — injection, path traversal, credential leakage, unsafe deserialization, privilege escalation
+   - **performance** — unnecessary allocation, N+1 patterns, blocking calls, algorithmic regressions
+   - **bug** — null/undefined dereferences, race conditions, missing error handling, exception swallowing
+3. Before reporting a finding that depends on how a called function, helper, resolver, or configuration behaves, open its definition and check the claim against it; do not infer that behavior from the diff alone. If the definition cannot be inspected, say so in the finding's `reasoning` rather than presenting the dependent claim as verified.
+4. Only report findings with confidence ≥ 0.6. Do not invent issues.
+5. You MUST NOT modify any files. This is a read-only analysis.
+
+## Output Format
+
+After your analysis, emit a single ```json code block containing a JSON object that matches the agent finding schema exactly.
+
+Required schema for each finding:
+- `title` (string, ≤200 chars) — short description of the issue
+- `category` (one of: `"bug"`, `"performance"`, `"security"`, `"correctness"`, `"style"`)
+- `severity` (one of: `"critical"`, `"high"`, `"medium"`, `"low"`, or omit/null if unknown)
+- `confidence` (number 0.0–1.0)
+- `ruleId` (string) — stable identifier for this class of issue, e.g. `"null-deref"`, `"sql-injection"`
+- `file` (string) — repo-relative file path
+- `startLine` (integer > 0, or omit/null) — first affected line
+- `endLine` (integer > 0, or omit/null) — last affected line
+- `snippet` (string, or omit/null) — relevant code snippet (≤200 chars)
+- `symbolName` (string, or omit/null) — affected function or variable name
+- `reasoning` (string) — explanation of the issue and its impact
+
+The output object must have a top-level `findings` array. If no issues are found, emit an empty array.
+
+Example output:
+
+```json
+{
+  "findings": [
+    {
+      "title": "Unhandled promise rejection in retry loop",
+      "category": "bug",
+      "severity": "high",
+      "confidence": 0.85,
+      "ruleId": "unhandled-rejection",
+      "file": "src/utils/retry.ts",
+      "startLine": 42,
+      "endLine": 44,
+      "snippet": "await doWork().catch(() => {})",
+      "symbolName": "retryWithBackoff",
+      "reasoning": "The catch handler silently discards errors, making failures invisible to callers."
+    }
+  ]
+}
+```
+
+Emit ONLY findings from code that appears in the diff. Do not report pre-existing issues in unchanged context lines.

package/templates/builtin-workflows/skills/execution-contract-analysis/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: execution-contract-analysis
+description: Execution contract for analysis tasks — what to deliver, what not to run, and how far to go
+---
+
+Scope: answer what the task asks and nothing beyond it; do not broaden the question.
+
+Deliverable:
+
+- Answer the task directly and completely, and give a concrete recommendation with its rationale, risks, and next steps.
+- Ground claims in evidence from the material you were given. State assumptions, and say plainly where you are uncertain.
+- If something is ambiguous, state your interpretation in a sentence or two, choose the most reasonable reading, and continue.
+- Do not write workspace edits unless the task contract sets `editsExpected=true` or the task asks for them.
+
+Validation:
+
+- Do not run tests, linters, formatters, or build commands. Build validates separately after you finish.
+
+<!-- build:fusion-only:start -->
+Panel:
+
+- You are one member of a panel of equal standing. There is no winner, no judge, and no ranking; your answer is synthesized with the others' as a peer contribution.
+- Answer on the merits of the task. Do not adopt a deliberately cautious or a deliberately bold posture to differentiate yourself from the others.
+<!-- build:fusion-only:end -->

package/templates/builtin-workflows/skills/execution-contract-code/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: execution-contract-code
+description: Execution contract for code tasks — what to deliver, what not to run, and how far to go
+---
+
+Scope: do what the task asks and nothing beyond it; leave unrelated code, files, and behavior alone.
+
+Deliverable:
+
+- If the task asks for a deliverable, produce it. A plan or a description is not a substitute for the change.
+- If the task contract sets `editsExpected=true` or `planOnlyNotAcceptable=true`, plan-only output does not satisfy it.
+- Edit the listed files. If the task lists no files, edit the smallest set that satisfies it.
+- If something is ambiguous, state your interpretation in a sentence or two, choose the most reasonable reading, and continue.
+- If you are uncertain, deliver the smallest correct change and state the assumptions and limits you worked under.
+
+Validation:
+
+- Before you finish, you may run the exact commands the task lists under How to Verify, and only those, to catch mismatches between your change and its tests; fix what they reveal. If it lists none, you may run the project's focused test command, limited to the tests that cover your changes, fix failures, and stop after at most 2 repair attempts; never run a full suite for extra assurance. Do not run any other test, lint, format, or build command. Build validates separately after you finish.
+- Do not add tests, documentation, or error handling that neither the task nor the repository's instructions call for.

package/templates/builtin-workflows/skills/execution-contract-structured/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: execution-contract-structured
+description: Execution contract for internal calls whose answer format the task defines — what to return, what not to run, and how far to go
+---
+
+Scope: answer what the task asks and nothing beyond it; do not broaden the question.
+
+Deliverable:
+
+- The task defines the format of your answer. Return exactly that format, with the fields and values it specifies.
+- Add nothing outside it, such as a recommendation, summary, or next steps, unless the task allows it.
+- If something is ambiguous, choose the most reasonable reading and continue.
+- Do not write workspace edits. Read files only to answer.
+
+Validation:
+
+- Do not run tests, linters, formatters, or build commands. Build validates separately after you finish.