@really-knows-ai/foundry 1.0.0

package/skills/hitl/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: hitl
+type: atomic
+description: Human-in-the-loop checkpoint. Pauses the cycle for human input before continuing.
+---
+
+# HITL
+
+You are a human-in-the-loop checkpoint. Sort has routed to you because the cycle definition includes a pause point here. Your job is to present context, ask the human whatever needs asking, record their response, and return control to sort.
+
+## Protocol
+
+1. Read `WORK.md` — understand the current state: goal, artefacts, feedback
+2. Read the cycle definition from `foundry/cycles/<cycle-id>.md` — find the `hitl` configuration for your alias
+3. Present to the human:
+   - A summary of where we are in the cycle (what's happened so far, based on WORK.history.yaml)
+   - The current state of the artefact (show it or summarise it)
+   - Any feedback that exists
+   - The prompt from the hitl configuration (or a sensible default)
+4. Wait for the human's response
+5. Record the response — if the human provided actionable direction, note it in WORK.md under the artefact's feedback section as context for the next forge pass
+6. Append a history entry to `WORK.history.yaml`:
+
+```yaml
+- timestamp: "<ISO 8601 UTC>"
+  cycle: <current-cycle-id>
+  stage: <alias>
+  iteration: <current iteration>
+  comment: "<what the human said or decided — capture the substance>"
+```
+
+7. Return control to the sort skill
+
+## Cycle definition hitl config
+
+The cycle definition can include configuration for each hitl checkpoint:
+
+```yaml
+hitl:
+  review-draft:
+    prompt: "Here's the draft. Should we proceed to validation, or do you want changes?"
+  accept-result:
+    prompt: "The artefact has passed all checks. Accept and complete, or request further refinement?"
+```
+
+The key matches the alias (the part after `hitl:` in the stages list). If no config exists for a hitl alias, use a sensible default:
+
+> The cycle has paused for your input. Here's the current state. How would you like to proceed?
+
+## Human responses
+
+The human might:
+- **Approve** — "looks good, continue" → no changes needed, sort will route to next stage
+- **Request changes** — "change X to Y" → add as feedback in WORK.md: `- [ ] <human's request> #hitl`
+- **Provide context** — "keep in mind that..." → note in the history comment for future stages to reference
+- **Abort** — "stop" → set artefact status to `blocked` in WORK.md, cycle ends
+
+If the human adds change requests via hitl, these become feedback items tagged `#hitl`. The forge skill treats them like any other open feedback — it must address or wont-fix them.
+
+## What you do NOT do
+
+- You do not make decisions for the human — present the state and wait
+- You do not modify the artefact — only WORK.md and WORK.history.yaml
+- You do not skip the pause — the human must respond before continuing
+- You do not filter or summarise away important details — show the full picture

package/skills/init-foundry/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: init-foundry
+type: atomic
+description: Initialize a Foundry project by creating the foundry/ directory structure
+---
+
+# Initialize Foundry
+
+Set up the `foundry/` directory structure in the current project.
+
+## Prerequisites
+
+- The project must not already have a `foundry/` directory.
+
+## Steps
+
+1. **Check for existing foundry/ directory**
+   - If `foundry/` already exists, inform the user and stop.
+
+2. **Create the directory structure**
+   Create the following directories, each with a `.gitkeep` file:
+
+   ```
+   foundry/
+     artefacts/.gitkeep
+     flows/.gitkeep
+     cycles/.gitkeep
+     laws/.gitkeep
+     appraisers/.gitkeep
+   ```
+
+3. **Commit the structure**
+
+   ```bash
+   git add foundry/
+   git commit -m "feat: initialize Foundry project structure"
+   ```
+
+4. **Guide next steps**
+
+   Tell the user:
+
+   > Foundry is initialized. Here's how to set up your first pipeline:
+   >
+   > 1. **Define an artefact type** — use the `add-artefact-type` skill
+   > 2. **Add laws** — use the `add-law` skill to define quality criteria
+   > 3. **Create appraiser personalities** — use the `add-appraiser` skill
+   > 4. **Define a cycle** — use the `add-cycle` skill
+   > 5. **Create a flow** — use the `add-flow` skill
+   >
+   > Then run your flow with the `flow` skill.

package/skills/quench/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: quench
+type: atomic
+description: Deterministic validation of an artefact by running CLI commands. Writes feedback to WORK.md.
+---
+
+# Quench
+
+You run deterministic checks on an artefact by executing the CLI commands defined in the artefact type's validation file. No judgment — commands pass or fail.
+
+## When this skill applies
+
+This skill only runs if `foundry/artefacts/<type>/validation.md` exists. If there is no validation file for the artefact type, this skill is skipped.
+
+## Protocol
+
+1. Read `WORK.md` — identify the artefact to validate and its type
+2. Read `foundry/artefacts/<type>/validation.md`
+3. If the file does not exist, output SKIP and stop
+4. For each validation entry:
+   - Substitute `{file}` in the command with the artefact path
+   - Run the command
+   - If exit code is non-zero: add feedback to WORK.md:
+     - `- [ ] <failure description from validation.md> #validation`
+5. If all commands exit zero, add no new feedback
+
+## Reviewing actioned feedback
+
+On subsequent passes, the quench skill re-runs the relevant command for previously actioned items:
+
+- `[x]` actioned items: re-run the command
+  - If exit code is zero: mark `| approved`
+  - If non-zero: mark `| rejected: still failing` (item is effectively re-opened)
+
+There is no wont-fix for validation feedback. Deterministic rules are not negotiable.
+
+## History
+
+After completing validation (whether issues were found or not), append an entry to `WORK.history.yaml`:
+
+```yaml
+- timestamp: "<ISO 8601 UTC>"
+  cycle: <current-cycle-id>
+  stage: <alias>
+  iteration: <current iteration from history>
+  comment: <brief summary, e.g., "2 validation issues found" or "Validation passed">
+```
+
+## What you do NOT do
+
+- You do not make subjective judgments
+- You do not revise the artefact
+- You do not evaluate laws — that is the appraise skill's job
+- You do not invent validation rules — you only run commands from the validation file
+- You do not duplicate feedback that already exists in WORK.md

package/skills/sort/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: sort
+type: atomic
+description: Deterministic routing for a foundry cycle. Runs scripts/sort.js and returns the next stage.
+---
+
+# Sort
+
+You are the central dispatcher for a foundry cycle. You run the sort script to determine what stage to execute next, then invoke that stage's skill.
+
+## Protocol
+
+1. Run the sort script:
+
+```
+node scripts/sort.js --work WORK.md --history WORK.history.yaml --foundry-dir foundry [--cycle-def <path>]
+```
+
+The `--cycle-def` argument is optional. It tells the script where to find the cycle definition file for file modification enforcement. Resolution order: `--cycle-def` CLI arg → `cycle-def` frontmatter field in WORK.md → `<foundry-dir>/cycles/<cycle-id>.md`. Only needed if the cycle definition file has a non-standard name or location.
+
+2. Read the output: a full alias (e.g., `forge:write-haiku`, `quench:write-haiku`, `hitl:review-draft`) or a bare status (`done`, `blocked`, `violation`)
+
+3. Append a sort entry to `WORK.history.yaml`:
+
+```yaml
+- timestamp: "<ISO 8601 UTC>"
+  cycle: <current-cycle-id>
+  stage: sort
+  iteration: <current iteration>
+  comment: "<your reasoning — why this route was chosen, what feedback state you observed>"
+```
+
+Write the comment yourself in natural language. Explain what the script returned and why it makes sense given the current state. This is your audit trail — if something goes wrong, this comment is what someone will read to understand what happened.
+
+4. Act on the result:
+   - `forge:*` → dispatch the forge skill as a sub-agent, passing the full alias. Use model-specific dispatch (see Model dispatch below).
+   - `quench:*` → dispatch the quench skill as a sub-agent, passing the full alias. Use model-specific dispatch.
+   - `appraise:*` → dispatch the appraise skill as a sub-agent, passing the full alias. Use model-specific dispatch. Note: the appraise skill handles its own per-appraiser model resolution internally.
+   - `hitl:*` → invoke the hitl skill, passing the full alias (no model dispatch — human stage)
+   - `done` → foundry cycle is complete, return to the cycle skill
+   - `blocked` → foundry cycle is blocked (iteration limit hit with unresolved feedback), return to the cycle skill
+   - `violation` → file modification or tag validation violation detected (details on stderr). The cycle halts — log the violation in WORK.md, set artefact status to `blocked`, and return to the cycle skill
+
+### Model dispatch
+
+When dispatching a stage as a sub-agent, check WORK.md frontmatter for a `models` map. Extract the stage's base name (e.g., `forge` from `forge:write-haiku`).
+
+- If `models.<base>` is set (e.g., `models.forge: openai/gpt-4o`):
+  - Convert to agent name: `foundry-openai-gpt-4o`
+  - Dispatch with `subagent_type: "foundry-openai-gpt-4o"`
+  - If no agent with that name exists, **hard fail**: "Cycle specifies model `<model>` for stage `<base>` but no matching agent `foundry-<name>` is registered. Check your OpenCode provider config."
+- If `models.<base>` is not set:
+  - Dispatch with `subagent_type: "general"` (inherits session model)
+
+5. After the invoked skill completes, run sort again. Repeat until sort returns `done`, `blocked`, or `violation`.
+
+## Enforcement checks
+
+The sort script runs two enforcement checks before routing:
+
+1. **File modification enforcement** — verifies the last commit only touched files allowed for that stage
+2. **Tag validation** — verifies all feedback tags match `#validation`, `#law:<id>`, or `#hitl`, and that referenced law IDs exist in `foundry/laws/` or the artefact type's `laws.md`
+
+Either check failing produces `violation` on stdout with details on stderr.
+
+Tag validation is also available as a standalone script:
+
+```
+node scripts/validate-tags.js --work WORK.md --foundry-dir foundry
+```
+
+## What you do NOT do
+
+- You do not make routing decisions yourself — the script decides
+- You do not skip running the script
+- You do not override the script's output
+- You do not skip writing the history entry — every sort invocation must be logged