@bendyline/gilde 0.1.26 → 0.1.28

package/data/craftbook-templates/gr/graphql-api/versions/1.0.2/craftbook.json

@@ -0,0 +1,146 @@
+{
+  "id": "graphql-api",
+  "name": "GraphQL API",
+  "description": "Build a GraphQL API with a typed schema (SDL), resolvers, queries, mutations, and input validation. Designs the schema FIRST — types, fields, nullability, query/mutation operations, and the resolver-to-data mapping — because in GraphQL the schema IS the contract, then implements resolvers, then writes operation tests covering each query, mutation, and error. Covers GraphQL schema definition language, resolvers, nullable vs non-null fields, mutations, query arguments, N+1 awareness, and error handling.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Schema design (planner) — lock the SDL types, queries, mutations, nullability → gated on artifact `notes/schema-design.md` (markdown-notes)\n2. Build resolvers (developer) — implement the schema + resolvers → gated on `src/schema.js` (code-module)\n3. Write operation tests (developer) — test each query, mutation, and error → gated on `src/schema.test.js` (code-with-tests)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "schema-design",
+  "triggers": [
+    "build a graphql api",
+    "graphql schema and resolvers",
+    "create a graphql server",
+    "graphql endpoint"
+  ],
+  "steps": [
+    {
+      "id": "schema-design",
+      "name": "Schema design",
+      "description": "lock the SDL types, queries, mutations, nullability",
+      "prompt": "Design the GraphQL schema before any resolver code — in GraphQL the schema is the contract. Step 1: Define the object types and their fields in SDL, deciding nullability (`String` vs `String!`) deliberately for each field. Step 2: Define the root `Query` operations (what can be read) and `Mutation` operations (what can be changed), with their argument types and input types. Step 3: For each operation, note which data source/store backs it and what a resolver must return. Step 4: Decide error handling: which conditions return null vs throw a typed GraphQL error, and the shape of user-facing errors. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'querying user(id) returns the user or null', 'createUser mutation validates input and returns the created node', 'a non-null field never resolves to null', 'invalid input yields a GraphQL error, not a crash'). `write_task_note` the SDL + checklist and write the same to the produces path. No resolvers yet.\n\nThe deliverable `notes/schema-design.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "planner",
+      "advanceWhen": {
+        "file": "notes/schema-design.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/schema-design.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/schema-design.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "schema-design",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build resolvers",
+      "description": "implement the schema + resolvers",
+      "prompt": "Implement the GraphQL server in a single runnable source file. Step 1: Declare the schema exactly as designed (SDL string or schema-builder calls) — same types, fields, nullability, operations. Step 2: Write a resolver for every Query and Mutation field; resolvers must honor the declared return types and nullability. Step 3: Validate mutation inputs before mutating; on invalid input throw a typed GraphQL error with a clear message. Step 4: Use an in-memory store if no DB was specified, and make sure non-null fields are always populated. On a loop-back, fix only the named gaps without regressing working resolvers. `write_task_note` the file path and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/schema.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/schema.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/schema.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/schema.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/schema.js"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "test"
+    },
+    {
+      "id": "test",
+      "name": "Write operation tests",
+      "description": "test each query, mutation, and error",
+      "prompt": "Write tests that execute real GraphQL operations against the schema. Step 1: For each Query, assert the returned shape matches the SDL (including nulls where allowed). Step 2: For each Mutation, assert the happy path returns the created/updated node, then assert invalid input produces a GraphQL error rather than a crash. Step 3: Add a test proving a non-null field never resolves to null. Step 4: Add a create-then-query round-trip to prove state wiring. Make tests runnable and self-contained. `write_task_note` the test file path and pass/fail count.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/schema.test.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/schema.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/schema.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/schema.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/schema.js"
+          }
+        ],
+        "onReject": "test",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Run the tests and execute sample operations. For EACH acceptance criterion: confirm queries return the SDL-correct shape and nullability, confirm mutations validate input and return the right node, confirm invalid input yields a typed GraphQL error (not a crash), and confirm non-null fields are never null. Write PASS/FAIL per criterion.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"build\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "src/schema.js"
+        }
+      ],
+      "next": "build"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.2",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}

package/data/craftbook-templates/gr/graphql-api/versions/1.0.2/test.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "title": "GraphQL API smoke eval",
+  "objective": "Self-contained smoke eval for the GraphQL API craftbook using the code generic harness.",
+  "tags": [
+    "code"
+  ],
+  "prompt": "We need a small Node helper for this — the requirments are in source/requirements.md. Put it in src/solution.mjs.",
+  "setup": {
+    "projectName": "GraphQL API Eval",
+    "about": "Self-contained eval project for graphql-api. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/src/solution.mjs.",
+    "missionObjectives": "Use the GraphQL API craftbook/template, read the seeded local fixtures, and write src/solution.mjs without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# GraphQL API Eval Brief\n\nClient: Boreal Desk, a home-office accessories company.\nAudience: operations leads who need an artifact they can use this week.\n\nFixed source facts for grounding:\n- The returns desk pilot covered 18 SKUs.\n- Median first response improved from 18 hours to 6 hours.\n- Preventable refund leakage fell from 14.2% to 8.9%.\n- The top unresolved complaint is status silence after photo submission.\n- Required next actions are automated status emails, barcode-exception training, and a weekly Finance exception export.\n\nUse these facts when the task asks for prose, analysis, copy, UI content, or test data. Do not use live web services, real credentials, or current outside data.\n\nCraftbook under test: graphql-api - GraphQL API.\n"
+      },
+      {
+        "path": "source/requirements.md",
+        "content": "# Runner Requirements\n\nBuild a dependency-free Node ESM helper for Boreal Desk support operations. Export at least one function. Include a tiny self-test section using node:assert or an equivalent assertion helper. Use fixture values for 18 -> 6 hour response time and 14.2 -> 8.9 refund leakage.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Developer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "src/solution.mjs is a local ESM module with basic self-test scaffolding.",
+    "deliverables": [
+      {
+        "path": "src/solution.mjs",
+        "kind": "code-with-tests",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "esmImports",
+            "file": "src/solution.mjs"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "export\\s+(function|const|class)|export\\s*\\{",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "assert|test|describe|it|expect",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "18|6|14\\.2|8\\.9|Boreal",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "src/solution.mjs",
+      "kind": "typescript"
+    },
+    "axes": [
+      {
+        "name": "correctness",
+        "description": "The module does what the requirements ask, with sensible edge handling."
+      },
+      {
+        "name": "verification",
+        "description": "Self-tests exercise real behavior, not trivial truths."
+      },
+      {
+        "name": "clarity",
+        "description": "Exports, naming, and structure make the module usable without reading every line."
+      },
+      {
+        "name": "robustness",
+        "description": "Invalid input and boundary cases fail loudly rather than silently."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "runnable ESM",
+    "test scaffolding",
+    "local fixtures"
+  ]
+}

package/data/craftbook-templates/gr/grpc-service/versions/1.0.1/craftbook.json

@@ -0,0 +1,147 @@
+{
+  "id": "grpc-service",
+  "name": "gRPC Service",
+  "description": "Build a gRPC service from a Protocol Buffers contract — define the .proto service and messages, implement the server handlers, and verify with client calls including streaming and status codes. Designs the proto contract FIRST — the service, RPC methods, request/response messages, field numbers, and the streaming kinds — because the .proto is the binding contract across languages, then implements the handlers, then tests unary/streaming calls and gRPC status codes. Covers protobuf service/message definitions, field numbering, unary vs server/client/bidi streaming, gRPC status codes, deadlines, and a client-driven test.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Proto contract design (planner) — lock the service, methods, messages, streaming kinds → gated on artifact `notes/proto-design.md` (markdown-notes)\n2. Build the service (developer) — write the .proto + implement the server handlers → gated on `src/server.js` (code-module)\n3. Test with a client (developer) — test unary/streaming calls and status codes → gated on `src/server.test.js` (code-with-tests)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "proto-design",
+  "triggers": [
+    "build a grpc service",
+    "protobuf service and server",
+    "implement grpc handlers",
+    "create a .proto and server",
+    "rpc service"
+  ],
+  "steps": [
+    {
+      "id": "proto-design",
+      "name": "Proto contract design",
+      "description": "lock the service, methods, messages, streaming kinds",
+      "prompt": "Design the Protocol Buffers contract before any server code — the .proto is the binding cross-language contract. Step 1: Define the service and its RPC METHODS, choosing the streaming kind for each (unary, server-streaming, client-streaming, bidi). Step 2: Define the request and response MESSAGE types with explicit, stable FIELD NUMBERS and correct scalar/enum/repeated types. Step 3: Decide the gRPC STATUS-CODE map: which conditions return OK, INVALID_ARGUMENT, NOT_FOUND, ALREADY_EXISTS, etc., and how errors carry detail. Step 4: Note deadlines/timeouts expectations. Step 5: Write a numbered acceptance-criteria checklist of 5-9 items (e.g. 'each RPC has the documented signature and streaming kind', 'invalid input returns INVALID_ARGUMENT not OK', 'a missing entity returns NOT_FOUND', 'field numbers are stable and unique'). `write_task_note` the proto draft + status map + checklist and write the same to the produces path.\n\nThe deliverable `notes/proto-design.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "planner",
+      "advanceWhen": {
+        "file": "notes/proto-design.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/proto-design.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/proto-design.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "proto-design",
+        "maxAttempts": 3
+      },
+      "next": "build"
+    },
+    {
+      "id": "build",
+      "name": "Build the service",
+      "description": "write the .proto + implement the server handlers",
+      "prompt": "Implement the gRPC service to the contract. Step 1: Write the `.proto` file exactly as designed — service, methods with their streaming kinds, and messages with their field numbers. Step 2: Implement a server handler for every RPC; honor the streaming kind (stream responses for server-streaming, consume the stream for client-streaming). Step 3: Validate requests and return the correct gRPC STATUS CODE on each error condition (INVALID_ARGUMENT, NOT_FOUND, ...), never a generic UNKNOWN for an expected error. Step 4: Respect deadlines and use an in-memory store if none specified. Write the server source to the produces path (and the .proto alongside it). On a loop-back, fix only the named gaps. `write_task_note` the file paths and which criteria now pass.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/server.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/server.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/server.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/server.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/server.js"
+          }
+        ],
+        "onReject": "build",
+        "maxAttempts": 3
+      },
+      "next": "test"
+    },
+    {
+      "id": "test",
+      "name": "Test with a client",
+      "description": "test unary/streaming calls and status codes",
+      "prompt": "Write client-driven tests against the running service. Step 1: For each unary RPC, call it and assert the response message matches the proto and the status is OK. Step 2: For streaming RPCs, drive the stream and assert the sequence of messages is correct. Step 3: Trigger each error condition and assert the correct gRPC STATUS CODE comes back (INVALID_ARGUMENT on bad input, NOT_FOUND on missing), not OK or UNKNOWN. Step 4: Add a round-trip (create then fetch) to prove state wiring. `write_task_note` the test file path and pass/fail count.",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "src/server.test.js",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "src/server.js",
+            "bytes": 200
+          },
+          {
+            "kind": "sniff",
+            "file": "src/server.js",
+            "sniff": "nonempty"
+          },
+          {
+            "kind": "esmImports",
+            "file": "src/server.js"
+          },
+          {
+            "kind": "sourceParses",
+            "file": "src/server.js"
+          }
+        ],
+        "onReject": "test",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Run the tests with a gRPC client. For EACH acceptance criterion: confirm each RPC's signature/streaming kind works and unary responses match the proto, confirm streaming RPCs yield the right message sequence, confirm error conditions return the correct gRPC status code (not OK/UNKNOWN), and confirm a round-trip works. Write PASS/FAIL per criterion.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"build\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "src/server.js"
+        }
+      ],
+      "next": "build"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}

package/data/craftbook-templates/gr/grpc-service/versions/1.0.1/test.json

@@ -0,0 +1,92 @@
+{
+  "schemaVersion": 1,
+  "title": "gRPC Service smoke eval",
+  "objective": "Self-contained smoke eval for the gRPC Service craftbook using the code generic harness.",
+  "tags": [
+    "code"
+  ],
+  "prompt": "We need a small Node helper for this — the requirments are in source/requirements.md. Put it in src/solution.mjs.",
+  "setup": {
+    "projectName": "gRPC Service Eval",
+    "about": "Self-contained eval project for grpc-service. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/src/solution.mjs.",
+    "missionObjectives": "Use the gRPC Service craftbook/template, read the seeded local fixtures, and write src/solution.mjs without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# gRPC Service Eval Brief\n\nClient: Boreal Desk, a home-office accessories company.\nAudience: operations leads who need an artifact they can use this week.\n\nFixed source facts for grounding:\n- The returns desk pilot covered 18 SKUs.\n- Median first response improved from 18 hours to 6 hours.\n- Preventable refund leakage fell from 14.2% to 8.9%.\n- The top unresolved complaint is status silence after photo submission.\n- Required next actions are automated status emails, barcode-exception training, and a weekly Finance exception export.\n\nUse these facts when the task asks for prose, analysis, copy, UI content, or test data. Do not use live web services, real credentials, or current outside data.\n\nCraftbook under test: grpc-service - gRPC Service.\n"
+      },
+      {
+        "path": "source/requirements.md",
+        "content": "# Runner Requirements\n\nBuild a dependency-free Node ESM helper for Boreal Desk support operations. Export at least one function. Include a tiny self-test section using node:assert or an equivalent assertion helper. Use fixture values for 18 -> 6 hour response time and 14.2 -> 8.9 refund leakage.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Developer"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "src/solution.mjs is a local ESM module with basic self-test scaffolding.",
+    "deliverables": [
+      {
+        "path": "src/solution.mjs",
+        "kind": "code-with-tests",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "esmImports",
+            "file": "src/solution.mjs"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "export\\s+(function|const|class)|export\\s*\\{",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "assert|test|describe|it|expect",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "src/solution.mjs",
+            "pattern": "18|6|14\\.2|8\\.9|Boreal",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "src/solution.mjs",
+      "kind": "typescript"
+    },
+    "axes": [
+      {
+        "name": "correctness",
+        "description": "The module does what the requirements ask, with sensible edge handling."
+      },
+      {
+        "name": "verification",
+        "description": "Self-tests exercise real behavior, not trivial truths."
+      },
+      {
+        "name": "clarity",
+        "description": "Exports, naming, and structure make the module usable without reading every line."
+      },
+      {
+        "name": "robustness",
+        "description": "Invalid input and boundary cases fail loudly rather than silently."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "runnable ESM",
+    "test scaffolding",
+    "local fixtures"
+  ]
+}

package/data/craftbook-templates/ha/handbook-section/versions/1.0.1/craftbook.json

@@ -0,0 +1,145 @@
+{
+  "id": "handbook-section",
+  "name": "Team Handbook Section",
+  "description": "Write a clear, reference-grade section of a team/company handbook — a policy, process, or how-we-work doc that a new hire can read once and act on correctly. Scopes the policy's intent, audience, and edge cases FIRST, writes unambiguous prose with concrete examples, a quick-reference summary, and FAQ, then has a reviewer check it for ambiguity and contradictions with how things actually work. Use for onboarding docs, policy pages, process documentation, and internal wikis.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. Scope the section (planner) — intent, audience, what's in/out, and the tricky edge cases → gated on artifact `notes/scope.md` (markdown-notes)\n2. Write the section (copywriter) — unambiguous prose with examples, TL;DR, and FAQ → gated on `handbook.md` (markdown-doc)\n3. Review for clarity (reviewer) — hunt for ambiguity, contradictions, and unanswered edge cases → gated on artifact `notes/review.md` (markdown-notes)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "handbook section",
+    "write a policy",
+    "team handbook page",
+    "process documentation",
+    "internal wiki page",
+    "how we work doc"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the section",
+      "description": "intent, audience, what's in/out, and the tricky edge cases",
+      "prompt": "Define the policy/process before writing it. Step 1: state the section's intent — what behavior or knowledge it is trying to produce — and who reads it. Step 2: define what this section covers and what it explicitly does not (link-outs for the rest). Step 3: enumerate the edge cases and 'what if' questions people actually hit, because unhandled edge cases are where handbooks fail. Step 4: decide whether the topic is a POLICY (rules + rationale) or a PROCESS (ordered steps + owners) and structure accordingly. Step 5: write an acceptance-criteria checklist ('states intent up front', 'covers the enumerated edge cases', 'includes at least one concrete example', 'has a quick-reference summary (TL;DR)', 'unambiguous — no \"usually/it depends\" without resolution', 'owner/contact named for questions'). Write the scope + edge-case list + checklist via write_task_note AND to notes/scope.md. No prose yet.\n\nThe deliverable `notes/scope.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "planner",
+      "advanceWhen": {
+        "file": "notes/scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "notes/scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "notes/scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "scope",
+        "maxAttempts": 3
+      },
+      "next": "write"
+    },
+    {
+      "id": "write",
+      "name": "Write the section",
+      "description": "unambiguous prose with examples, TL;DR, and FAQ",
+      "prompt": "Write the handbook section as handbook.md so a new hire reads it once and acts correctly. Step 1: open with a one-line TL;DR / quick-reference summary capturing the rule or the steps at a glance. Step 2: state the intent/why briefly (people follow policy better when they understand it). Step 3: write the body — for a POLICY, the rules with rationale; for a PROCESS, NUMBERED steps with the owner/role for each — in plain, direct language. Step 4: include at least one concrete worked example showing the policy/process applied. Step 5: write a short FAQ resolving every enumerated edge case with a definite answer (no 'it depends' left dangling). Step 6: name the owner/contact for questions and the last-reviewed date. Avoid hedging where a decision is needed. On a loop-back, fix ONLY the named gaps. Write the path via write_task_note.",
+      "suggestedRole": "copywriter",
+      "advanceWhen": {
+        "file": "handbook.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "handbook.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "handbook.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "write",
+        "maxAttempts": 3
+      },
+      "next": "review"
+    },
+    {
+      "id": "review",
+      "name": "Review for clarity",
+      "description": "hunt for ambiguity, contradictions, and unanswered edge cases",
+      "prompt": "Review the section for the failure modes that make handbooks useless. Step 1: read it as a new hire and flag any sentence that leaves you unsure what to actually do. Step 2: check every enumerated edge case is answered definitively in the FAQ or body. Step 3: hunt for internal contradictions and for hedging ('usually', 'generally') where a firm answer is required. Step 4: confirm the TL;DR matches the detailed body and the example is correct. Step 5: list concrete gaps with the location and the fix, recorded as PASS/FAIL against the scope checklist. Write the findings via write_task_note AND to notes/review.md. Gaps must be fixed in the write phase before this passes.\n\nThe deliverable `notes/review.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "reviewer",
+      "advanceWhen": {
+        "file": "notes/review.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "handbook.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "handbook.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "review",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "QA the handbook section against the locked criteria. Step 1: read handbook.md as a brand-new hire. Step 2: check EACH acceptance criterion: a TL;DR/quick-reference is present and matches the body, the intent is stated up front, the body is unambiguous (no unresolved 'it depends'), every enumerated edge case is answered, at least one concrete example is present and correct, and an owner/contact is named. Step 3: confirm there are no internal contradictions, folding in notes/review.md findings. Write PASS/FAIL per criterion with the offending location on any FAIL.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"write\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "handbook.md"
+        }
+      ],
+      "next": "write"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.1",
+  "releasedAt": "2026-08-14T00:00:00Z"
+}