yet-another-agentic-workflow 0.2.0

package/schemas/state.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yaaw.dev/schemas/state.schema.json",
+  "title": "YAAW state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "path"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "path": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "durable": { "type": "boolean", "default": true }
+  }
+}

package/schemas/workflow.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yaaw.dev/schemas/workflow.schema.json",
+  "title": "YAAW workflow",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["name", "steps"],
+  "properties": {
+    "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "description": { "type": "string", "minLength": 1 },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "uses"],
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+          "uses": {
+            "type": "string",
+            "pattern": "^(skill|agent|hook|eval|workflow|context|state):[a-z][a-z0-9-]*$"
+          },
+          "needs": {
+            "type": "array",
+            "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" }
+          },
+          "with": { "type": "object" }
+        }
+      }
+    }
+  }
+}

package/schemas/yaaw.schema.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://yaaw.dev/schemas/yaaw.schema.json",
+  "title": "YAAW project definition",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "project",
+    "skills",
+    "agents",
+    "hooks",
+    "evals",
+    "workflows",
+    "context",
+    "state"
+  ],
+  "properties": {
+    "version": { "const": 1 },
+    "project": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+        "description": { "type": "string", "minLength": 1 }
+      }
+    },
+    "skills": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/skill.schema.json" }
+    },
+    "agents": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/agent.schema.json" }
+    },
+    "hooks": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/hook.schema.json" }
+    },
+    "evals": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/eval.schema.json" }
+    },
+    "workflows": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/workflow.schema.json" }
+    },
+    "context": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/context.schema.json" }
+    },
+    "state": {
+      "type": "array",
+      "items": { "$ref": "https://yaaw.dev/schemas/state.schema.json" }
+    }
+  }
+}

package/skills/clarify/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: clarify
+description: Resolve only the unknowns that materially change behavior, scope,
+  or the public testing seam.
+---
+# Clarify
+
+Resolve ambiguity from evidence before asking questions.
+
+1. Read the request, relevant conversation, repository instructions, domain documentation, ADRs, code, and nearby tests. Use the project's domain vocabulary.
+2. Separate facts that the repository can answer from unknowns that change observable behavior, scope, data contracts, or irreversible decisions.
+3. State the requested user-visible outcome and identify the highest existing public seam through which it can be verified. Prefer an existing seam; propose a new one only when the behavior cannot be observed otherwise.
+4. Ask one focused question only when competing answers would produce meaningfully different implementations and no repository evidence resolves them. Otherwise record the smallest reasonable assumption.
+5. Produce resolved decisions, assumptions, the selected public seam, remaining unknowns, and the next action. Stop when specification work is unblocked.

package/skills/code-review/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: code-review
+description: Review a fixed change set against either the specification or
+  engineering standards without letting one axis mask the other.
+---
+# Code review
+
+Review one axis only. The workflow invokes separate spec and standards reviewers so their evidence and verdicts remain independent.
+
+## Establish the review set
+
+1. Pin the fixed point from the supplied diff, commit, branch, transaction artifact, or persisted workflow record. Confirm that the change set is non-empty.
+2. Inspect changed code and recorded verification evidence. Do not expand the review into unrelated pre-existing code.
+3. Load only the evidence for the assigned axis.
+
+## Spec axis
+
+Compare the change with the originating specification and acceptance criteria. Find missing or partial behavior, behavior that appears implemented incorrectly, and unrequested scope creep. Cite the criterion and changed file or hunk for every finding. If no specification exists, report that the axis was not assessable rather than inventing requirements.
+
+## Standards axis
+
+Apply documented repository standards first; they override generic heuristics. Then use this compact smell baseline as judgement, not automatic failure: mysterious names, duplicated logic, data clumps or primitive obsession, repeated conditionals, shotgun surgery or divergent change, speculative generality, message chains, and middle-man abstractions. Skip concerns already enforced by successful tooling.
+
+## Verdict
+
+- Report each finding with a stable code, severity, file or hunk, evidence, and the smallest corrective direction.
+- Distinguish documented violations from judgement calls.
+- Return explicit `PASS` with no findings, or `FAIL` with at least one evidence-backed finding.
+- Remain read-only: do not repair the implementation from the reviewer role.

package/skills/slice-work/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: slice-work
+description: Turn a specification into tracer-bullet slices with acceptance
+  criteria, testing seams, and explicit blocking edges.
+---
+# Slice work
+
+Build a dependency graph of tracer-bullet vertical slices, not a layer-by-layer task list.
+
+1. Make each slice deliver one narrow but complete user-visible behavior through every relevant layer. A completed slice must be demonstrable or verifiable on its own and fit within one fresh working context.
+2. Give each slice an ID, title, delivered behavior, acceptance criteria, public verification seam, verification command or method, and `blockedBy` IDs.
+3. Keep blocking edges real: a slice depends only on work that must exist before it can start. Order blockers first and identify the current frontier—all slices whose blockers are complete.
+4. Prefer the smallest end-to-end slice first. Add a prefactoring slice only when it independently keeps verification green and materially makes the behavior change easier.
+5. Treat wide mechanical refactors as the exception. Use expand–contract: add the new form beside the old, migrate bounded batches while verification stays green, then remove the old form after all migrations.
+6. Avoid predicted file paths and speculative implementation detail. Preserve the specification's domain language and observable boundaries.

package/skills/spec/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: spec
+description: Synthesize repository evidence and resolved decisions into
+  behavior, seams, and independently verifiable acceptance criteria.
+---
+# Specification
+
+Synthesize what is already known; do not restart the requirements interview. Use repository domain vocabulary and respect applicable ADRs.
+
+## Required specification
+
+- **Problem and goal:** the user's problem and the outcome that resolves it.
+- **User-visible solution:** numbered user stories or scenarios that describe actors, behavior, and benefit.
+- **Expected behavior:** normal flow, consequential failure states, and externally visible state transitions.
+- **Implementation decisions:** durable contracts, schema or API decisions, and architectural constraints. Avoid speculative file paths and code snippets.
+- **Testing decisions:** select the highest existing public seam that can prove the behavior, name prior test patterns to follow, and justify any new seam.
+- **Constraints and non-goals:** explicit boundaries that prevent scope drift.
+- **Acceptance criteria:** independently verifiable observations with an unambiguous source of truth.
+- **Important decisions and unknowns:** preserve rationale and identify only unresolved items that can still change delivery.
+
+Prefer fewer, higher-leverage seams. Tests should observe behavior through public interfaces and remain valid when internals are refactored.

package/skills/tdd/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: tdd
+description: Deliver one vertical slice at a time with public-interface tests,
+  boundary-only mocks, and recorded red-green evidence.
+---
+# Test-driven development
+
+Work one acceptance criterion and one pre-agreed public seam at a time. Read relevant domain documentation and ADRs so test names and interfaces use repository language.
+
+## Test quality
+
+- Verify behavior through the public interface at the selected seam. Tests should survive internal refactoring and read as executable specifications.
+- Derive expected results from an independent source of truth: a known literal, worked example, contract, or acceptance criterion.
+- Avoid **implementation-coupled** tests of private methods, internal collaborators, call order, or incidental storage.
+- Avoid **tautological** assertions that recompute the result with the same logic as production code.
+- Mock only at system boundaries such as external APIs, time, randomness, or an unavailable external store. Prefer real controlled dependencies and never mock code the project owns merely to make a test easy.
+
+## Red-green-refactor cycle
+
+1. Confirm the active criterion and public seam. Write one focused behavioral test.
+2. Run it and record RED: exact command, relevant failure, and non-zero status. A test that passes immediately does not prove the change.
+3. Implement the smallest production change that produces GREEN. Do not anticipate later slices or add speculative generality.
+4. Run the focused test and record GREEN. Refactor only the code exercised by the slice, without changing behavior, and keep the focused test green.
+5. Repeat with the next behavior learned from the previous cycle; do not write a horizontal batch of imagined tests up front.
+6. Run relevant typechecking and focused tests during work, then the full required verification suite once the slice is complete. Record commands, outputs, and exit statuses.

package/templates/instructions/managed-block.md

@@ -0,0 +1,17 @@
+<!-- yaaw:start -->
+
+## Yet Another Agentic Workflow
+
+This repository uses YAAW engineering skills.
+
+Use the installed skills when their procedure matches the task.
+
+For meaningful implementation work:
+
+- resolve consequential ambiguity before coding;
+- establish observable acceptance criteria;
+- prefer small independently verifiable slices;
+- use feedback loops rather than guessing;
+- verify before declaring work complete.
+
+<!-- yaaw:end -->