@really-knows-ai/foundry 1.2.1 → 1.3.0

package/skills/forge/SKILL.md

@@ -6,7 +6,7 @@ description: Produces or revises an artefact, guided by WORK.md and the foundry
 
 # Forge
 
-You produce or revise artefacts. You read WORK.md to understand the goal and feedback, and the foundry cycle definition to understand what you're producing and what inputs you can read.
+You produce or revise artefacts. You read the work file to understand the goal and feedback, and the foundry cycle definition to understand what you're producing and what inputs you can read.
 
 ## Prerequisites
 
@@ -16,59 +16,43 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## Protocol
 
-### First generation (no artefact registered in WORK.md yet)
+### First generation (no artefact registered yet)
 
-1. Read `WORK.md` — understand the goal
-2. Read the foundry cycle definition from `foundry/cycles/<cycle-id>.md` — understand what to produce and what inputs are available
-3. Read the output artefact type definition from `foundry/artefacts/<type>/definition.md`
-4. Read all files in `foundry/laws/` for global laws
-5. Read `foundry/artefacts/<type>/laws.md` for type-specific laws (if it exists)
-6. If the foundry cycle has inputs, read the input artefacts (read-only context)
-7. Produce the artefact, respecting all applicable laws from the start
-8. Write the artefact to the location specified in the artefact type definition
-9. Register the artefact in the WORK.md artefacts table. The table MUST have all four columns — File, Type, Cycle, Status. Set cycle to the current cycle id from WORK.md frontmatter. Set status to `draft`.
+1. Call `foundry_workfile_get` — understand the goal
+2. Call `foundry_config_cycle` — understand what to produce and what inputs are available
+3. Call `foundry_config_artefact_type` with the output type ID — get the artefact type definition
+4. Call `foundry_config_laws` — get all applicable laws (global + type-specific)
+5. If the cycle has inputs, read the input artefacts (read-only context)
+6. Produce the artefact, respecting all applicable laws from the start (this is judgment — use your craft)
+7. Write the artefact file to the location specified in the artefact type definition
+8. Call `foundry_artefacts_add` with the file path, type, and cycle to register it with status `"draft"`
 
-### Revision (feedback exists in WORK.md)
+### Revision (feedback exists)
 
-1. Read `WORK.md` — find unresolved feedback items for the artefact. Feedback is scoped by file: look under `## Feedback` for the `### <file-path>` sub-heading that matches the artefact's File column in the artefacts table. Only items under that heading belong to this artefact.
-2. Read the artefact
-3. If the foundry cycle has inputs, read the input artefacts (read-only context)
+1. Call `foundry_feedback_list` to find unresolved feedback for the artefact
+2. Read the artefact file
+3. If the cycle has inputs, read the input artefacts (read-only context)
 4. For each unresolved feedback item, either:
-   - Address it and mark as `[x]` (actioned)
-   - Mark as `[~]` with justification if you believe the feedback should not be actioned: `- [~] <issue> #law:<id> | wont-fix: <reason>`
+   - Address it and call `foundry_feedback_action` with the item ID (marks as actioned)
+   - Call `foundry_feedback_wontfix` with the item ID and a justification (appraisal feedback only)
 5. Update the artefact file
-6. Wont-fix is only available for `#law:` feedback (subjective appraisal). Validation feedback (`#validation`) must be actioned — deterministic rules are not negotiable.
+6. Wont-fix is only available for `law:` feedback (subjective appraisal). Validation feedback must be actioned — deterministic rules are not negotiable.
 
-## Unresolved feedback
-
-An item is unresolved if it is:
-- `[ ]` — open, not yet addressed
-- `[x] ... | rejected: ...` — actioned but rejected by appraiser, effectively re-opened
-- `[~] ... | rejected` — wont-fix rejected by appraiser, effectively re-opened
-
-An item is resolved if it is:
-- `[x] ... | approved`
-- `[~] ... | approved`
+### After (both paths)
 
-## History
+Call `foundry_history_append` with the current cycle, the full stage alias (e.g., `forge:write-haiku`), and a brief description of what you did.
 
-After completing your work (first generation or revision), append an entry to `WORK.history.yaml`:
-
-```yaml
-- timestamp: "<ISO 8601 UTC>"
-  cycle: <current-cycle-id>
-  stage: <alias>
-  iteration: <n>
-  comment: <brief description of what you did>
-```
+## Unresolved feedback
 
-The `<alias>` is the full alias received from sort (e.g., `forge:write-haiku`). Use it exactly as given.
+An item is unresolved if it is:
+- `open` — not yet addressed
+- `rejected` — actioned or wont-fixed but rejected by appraiser, effectively re-opened
 
-The iteration number is one more than the count of existing `forge` entries for this cycle in the history.
+An item is resolved if it is `approved`.
 
 ## Feedback tagged `#hitl`
 
-Feedback tagged `#hitl` (human-in-the-loop) is treated the same as any other open feedback. Address it or wont-fix it using the same rules as other feedback items.
+Feedback tagged `hitl` (human-in-the-loop) is treated the same as any other open feedback. Address it or wont-fix it using the same rules as other feedback items.
 
 ## What you do NOT do
 

package/skills/hitl/SKILL.md

@@ -16,56 +16,33 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## 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)
+1. Gather context by calling:
+   - `foundry_workfile_get` — current state, goal, artefacts
+   - `foundry_config_cycle` — cycle definition and hitl configuration
+   - `foundry_history_list` — what has happened so far
+   - `foundry_feedback_list` — any existing feedback
+
+2. Present to the human:
+   - A summary of where we are in the cycle (what's happened so far)
    - 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`:
+   - The prompt from the hitl configuration (or a sensible default: "The cycle has paused for your input. Here's the current state. How would you like to proceed?")
 
-```yaml
-- timestamp: "<ISO 8601 UTC>"
-  cycle: <current-cycle-id>
-  stage: <alias>
-  iteration: <current iteration>
-  comment: "<what the human said or decided — capture the substance>"
-```
+3. Wait for the human's response.
 
-7. Return control to the sort skill
+4. Act on the response:
+   - **Approve** — "looks good, continue" — no changes needed, sort will route to next stage
+   - **Request changes** — call `foundry_feedback_add` with the human's request and tag `"hitl"`
+   - **Provide context** — note in the history comment for future stages to reference
+   - **Abort** — call `foundry_artefacts_set_status` with status `"blocked"`, cycle ends
 
-## Cycle definition hitl config
+5. Call `foundry_history_append` with the current cycle, stage alias, and a comment capturing the substance of what the human said or decided.
 
-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.
+6. Return control to the sort skill.
 
 ## 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 modify the artefact
 - 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/quench/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: quench
 type: atomic
-description: Deterministic validation of an artefact by running CLI commands. Writes feedback to WORK.md.
+description: Deterministic validation of an artefact by running CLI commands. Writes feedback via foundry tools.
 ---
 
 # 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.
+You run deterministic checks on an artefact by executing the CLI commands defined in the artefact type's validation config. No judgment — commands pass or fail.
 
 ## Prerequisites
 
@@ -14,62 +14,33 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 > Foundry is not initialized in this project. Run the `init-foundry` skill first to create the foundry/ directory structure.
 
-## 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 under the artefact's file heading
-5. If all commands exit zero, add no new feedback
-
-## Feedback format
-
-Feedback MUST be scoped to the artefact file it applies to. Under `## Feedback`, create a `### <file-path>` sub-heading matching the artefact's File column from the artefacts table, then write feedback items beneath it:
-
-```markdown
-## Feedback
-
-### foundry/output/haiku/pissed-off-spaghetti.md
-- [ ] The haiku does not have exactly 3 lines. #validation
-- [ ] One or more lines do not match the 5-7-5 syllable pattern. #validation
-```
-
-If the `## Feedback` section or the file sub-heading already exists, append items under the existing heading. Never write feedback items without a file sub-heading — the sort script cannot parse them.
+1. Call `foundry_workfile_get` to identify the artefact and its type.
+2. Call `foundry_config_validation` with the artefact type ID. If it returns null, output SKIP and stop — there is no validation for this type.
+3. Call `foundry_validate_run` with the type ID and artefact file path. It executes all validation commands and returns results.
+4. For each failure: call `foundry_feedback_add` with the artefact file path, a description of the failure, and tag `"validation"`.
+5. If all commands pass, add no new feedback.
 
 ## Reviewing actioned feedback
 
-On subsequent passes, the quench skill re-runs the relevant command for previously actioned items:
+On subsequent passes, review 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)
+1. Call `foundry_feedback_list` to find `actioned` items tagged `validation` for this artefact.
+2. Re-run the relevant command via `foundry_validate_run`.
+3. If the check now passes: call `foundry_feedback_resolve` with disposition `"approved"`.
+4. If it still fails: call `foundry_feedback_resolve` with disposition `"rejected"` and a reason.
 
 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">
-```
+After completing validation, call `foundry_history_append` with the current cycle, stage alias, and a 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
-- You do not write feedback items without a file sub-heading under `## Feedback`
+- You do not invent validation rules — you only run commands from the validation config
+- You do not duplicate feedback that already exists

package/skills/sort/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sort
 type: atomic
-description: Deterministic routing for a foundry cycle. Runs scripts/sort.js and returns the next stage.
+description: Deterministic routing for a foundry cycle. Runs the foundry_sort tool 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.
+You are the central dispatcher for a foundry cycle. You call the `foundry_sort` tool to determine what stage to execute next, then invoke that stage's skill.
 
 ## Prerequisites
 
@@ -16,68 +16,35 @@ Before running this skill, verify that the `foundry/` directory exists in the pr
 
 ## Protocol
 
-1. Run the sort script:
+1. Call `foundry_sort` (optionally passing `cycleDef` if the cycle definition has a non-standard path). It returns `{route, model?, details?}`.
 
-```
-node scripts/sort.js --work WORK.md --history WORK.history.yaml --foundry-dir foundry [--cycle-def <path>]
-```
+2. Call `foundry_history_append` with the current cycle, stage `"sort"`, and a comment explaining the routing decision in natural language. This is your audit trail — if something goes wrong, this comment is what someone will read to understand what happened.
 
-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
+3. Act on the route:
+   - `forge:*` — dispatch the forge skill as a sub-agent. Use model dispatch (see below).
+   - `quench:*` — dispatch the quench skill as a sub-agent. Use model dispatch.
+   - `appraise:*` — dispatch the appraise skill as a sub-agent. Use model dispatch. Note: the appraise skill handles its own per-appraiser model resolution internally.
+   - `hitl:*` — invoke the hitl skill (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 (see `details`). The cycle halts — call `foundry_artefacts_set_status` with status `"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`).
+Use the `model` field from the `foundry_sort` result to determine sub-agent routing:
 
-- If `models.<base>` is set (e.g., `models.forge: openai/gpt-4o`):
+- If `model` is set (e.g., `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:
+- If `model` is null:
   - 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
-```
+4. After the invoked skill completes, call `foundry_sort` again. Repeat until it returns `done`, `blocked`, or `violation`.
 
 ## 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
+- You do not make routing decisions yourself — the tool decides
+- You do not skip calling `foundry_sort`
+- You do not override the tool's output
+- You do not skip the history entry — every sort invocation must be logged via `foundry_history_append`