@really-knows-ai/foundry 1.0.0

package/.opencode/plugins/foundry.js

@@ -0,0 +1,106 @@
+/**
+ * Foundry plugin for OpenCode.ai
+ *
+ * Conditional bootstrap:
+ * - If foundry/ exists in project: full skill registration + pipeline context
+ * - If foundry/ does not exist: only init-foundry skill + minimal prompt
+ */
+
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '../..');
+const allSkillsDir = path.join(packageRoot, 'skills');
+const initSkillDir = path.join(allSkillsDir, 'init-foundry');
+
+function getBootstrapContent(directory) {
+  const foundryDir = path.join(directory, 'foundry');
+  const foundryExists = fs.existsSync(foundryDir) && fs.statSync(foundryDir).isDirectory();
+
+  if (!foundryExists) {
+    return `<FOUNDRY_CONTEXT>
+Foundry is installed but not initialized in this project. There is no foundry/ directory.
+
+To set up Foundry, use the \`init-foundry\` skill. This will create the foundry/ directory structure
+and guide you through defining artefact types, laws, appraisers, cycles, and flows.
+</FOUNDRY_CONTEXT>`;
+  }
+
+  return `<FOUNDRY_CONTEXT>
+Foundry is active in this project. The foundry/ directory contains the project's artefact definitions,
+laws, appraisers, cycles, and flows.
+
+Foundry is a skill-driven framework for governed artefact generation and evaluation.
+The pipeline: forge (produce) → quench (deterministic checks) → appraise (subjective evaluation) → iterate.
+
+Available skills:
+- **Pipeline:** forge, quench, appraise, cycle, flow, sort, hitl
+- **Helpers:** add-artefact-type, add-law, add-appraiser, add-cycle, add-flow, init-foundry
+
+Multi-model routing: The Foundry plugin has auto-registered \`foundry-*\` sub-agents for each available model.
+Cycle definitions can specify per-stage models via the \`models\` frontmatter map. Appraisers can override with their own \`model\` field.
+
+To start a flow, use the \`flow\` skill. All user content lives under foundry/.
+Scripts are located at: ${path.join(packageRoot, 'scripts')}
+</FOUNDRY_CONTEXT>`;
+}
+
+export const FoundryPlugin = async ({ client, directory }) => {
+  const foundryDir = path.join(directory, 'foundry');
+  const foundryExists = fs.existsSync(foundryDir) && fs.statSync(foundryDir).isDirectory();
+
+  return {
+    config: async (config) => {
+      config.skills = config.skills || {};
+      config.skills.paths = config.skills.paths || [];
+
+      if (foundryExists) {
+        if (!config.skills.paths.includes(allSkillsDir)) {
+          config.skills.paths.push(allSkillsDir);
+        }
+
+        // Register per-model subagents for multi-model stage routing
+        try {
+          const providers = await client.provider.list();
+          config.agent = config.agent || {};
+          for (const provider of providers) {
+            if (!provider.models) continue;
+            const modelKeys = Array.isArray(provider.models)
+              ? provider.models
+              : Object.keys(provider.models);
+            for (const modelKey of modelKeys) {
+              const agentName = `foundry-${provider.id}-${modelKey}`;
+              config.agent[agentName] = {
+                model: `${provider.id}/${modelKey}`,
+                mode: 'subagent',
+                hidden: true,
+                description: `Foundry stage agent using ${provider.id}/${modelKey}`,
+              };
+            }
+          }
+        } catch (err) {
+          console.warn('[foundry] Failed to discover models for agent registration:', err.message);
+        }
+      } else {
+        if (!config.skills.paths.includes(initSkillDir)) {
+          config.skills.paths.push(initSkillDir);
+        }
+      }
+    },
+
+    'experimental.chat.messages.transform': async (_input, output) => {
+      const bootstrap = getBootstrapContent(directory);
+      if (!bootstrap || !output.messages.length) return;
+
+      const firstUser = output.messages.find(m => m.info.role === 'user');
+      if (!firstUser || !firstUser.parts.length) return;
+
+      if (firstUser.parts.some(p => p.type === 'text' && p.text.includes('FOUNDRY_CONTEXT'))) return;
+
+      const ref = firstUser.parts[0];
+      firstUser.parts.unshift({ ...ref, type: 'text', text: bootstrap });
+    }
+  };
+};

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Really Knows AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,250 @@
+# Foundry
+
+A skill-driven framework for governed artefact generation and evaluation using AI coding tools. Install it as an npm package and define your own artefact types, laws, and flows — Foundry handles the forge-quench-appraise pipeline.
+
+## Compatibility
+
+- **OpenCode** — full support, multi-model routing via plugin-registered agents
+
+Multi-model support enables model diversity across pipeline stages. The Foundry plugin auto-discovers available models at startup and registers them as hidden sub-agents. Cycle definitions specify which model each stage uses. Tools limited to a single model lose model-diversity but still get personality-based diversity.
+
+## Installation
+
+Add `@really-knows-ai/foundry` to your OpenCode config:
+
+```json
+// opencode.json
+{
+  "packages": {
+    "@really-knows-ai/foundry": "latest"
+  }
+}
+```
+
+## Quick start
+
+1. **Install** the package as shown above
+2. **Initialize** — use the `init-foundry` skill to scaffold a `foundry/` directory in your project
+3. **Define artefact types** — use `add-artefact-type` to create types with file patterns, descriptions, and optional validation
+4. **Add laws** — use `add-law` to define subjective pass/fail criteria (global or per-type)
+5. **Add appraisers** — use `add-appraiser` to create appraiser personalities
+6. **Define cycles** — use `add-cycle` to wire artefact types into forge/quench/appraise loops
+7. **Define flows** — use `add-flow` to sequence cycles into end-to-end pipelines
+8. **Run** — use the `flow` skill to execute a flow
+
+## How it works
+
+```
+Foundry Flow
+ └─ Cycle 1 (e.g., ideation)
+ │   ├─ Forge → produce the artefact
+ │   ├─ Quench → deterministic CLI checks (if defined)
+ │   ├─ Appraise → subjective evaluation by multiple appraisers
+ │   └─ ↺ iterate until all feedback is resolved
+ └─ Cycle 2 (e.g., creation)
+     ├─ reads output from Cycle 1 (read-only)
+     ├─ Forge → produce the artefact
+     ├─ Quench → deterministic CLI checks
+     ├─ Appraise → subjective evaluation
+     └─ ↺ iterate until all feedback is resolved
+```
+
+A **foundry flow** runs one or more **foundry cycles** in sequence. Each cycle produces a single artefact type by looping through forge → quench → appraise until the artefact passes all criteria. The output of one cycle becomes read-only input for the next.
+
+All state lives in `WORK.md` on a dedicated work branch. Every stage micro-commits, and file modification enforcement ensures stages only touch what they're allowed to.
+
+## Core concepts
+
+### Foundry Flows
+
+Defined in `foundry/flows/`. A flow lists cycles to execute in order. Starting a flow creates a work branch and a fresh `WORK.md`.
+
+### Foundry Cycles
+
+Defined in `foundry/cycles/`. A cycle specifies:
+- `output` — the artefact type it produces (read-write)
+- `inputs` — artefact types from previous cycles (read-only)
+
+### Stages
+
+The three steps within a cycle:
+- **Forge** — produce or revise the artefact
+- **Quench** — run deterministic CLI checks (skipped if artefact type has no `validation.md`)
+- **Appraise** — subjective evaluation by multiple independent appraisers
+
+### Artefact types
+
+Defined in `foundry/artefacts/<type>/`. Each type has:
+- `definition.md` — id, name, file patterns, output directory, appraiser config, prose description
+- `laws.md` (optional) — type-specific subjective criteria
+- `validation.md` (optional) — CLI commands with `{file}` placeholder; non-zero exit = failure
+
+### Laws
+
+Subjective pass/fail criteria. Two scopes:
+- `foundry/laws/*.md` — global laws, all files concatenated, apply to everything
+- `foundry/artefacts/<type>/laws.md` — type-specific laws
+
+Each law is a `## heading` (the identifier, used in feedback tags as `#law:<id>`) with a description, passing criteria, and failing criteria.
+
+### Appraisers
+
+Defined in `foundry/appraisers/`. Each appraiser has a personality and an optional model override. Appraisers are assigned to artefact types via the `appraisers` section in the type's `definition.md`:
+
+```yaml
+appraisers:
+  count: 3                          # how many appraisers (default: 3)
+  allowed: [pedantic, pragmatic]    # which personalities (default: all available)
+```
+
+Appraisers are distributed evenly across available personalities for maximum diversity. If you request 6 appraisers with 3 personalities, you get 2 of each. Model diversity is configured at the cycle level (per-stage) and optionally per-appraiser — see [concepts](docs/concepts.md).
+
+### WORK.md
+
+Transient shared state on the work branch. Tracks:
+- Current position (flow, cycle, stage) in frontmatter
+- Goal description
+- Artefact registry (what exists, its status)
+- All feedback with full lifecycle
+
+### Feedback lifecycle
+
+```
+open         - [ ] issue #tag                                    → needs generator action
+actioned     - [x] issue #tag                                    → needs approval
+wont-fix     - [~] issue #tag | wont-fix: <reason>               → needs approval
+approved     - [x] issue #tag | approved                         → resolved
+approved     - [~] issue #tag | wont-fix: <reason> | approved    → resolved
+rejected     - [x] issue #tag | rejected: <reason>               → re-opened
+rejected     - [~] issue #tag | wont-fix: <reason> | rejected    → re-opened
+```
+
+Validation feedback (`#validation`) cannot be wont-fixed — deterministic rules are not negotiable.
+
+### File modification enforcement
+
+Every stage micro-commits. The cycle checks the git diff:
+- After forge: only output artefact file patterns + WORK.md + WORK.history.yaml (input artefacts are read-only — violation if touched)
+- After quench/appraise: only WORK.md + WORK.history.yaml
+- Violations are hard stops
+
+> **Merge hygiene:** WORK.md and WORK.history.yaml are ephemeral working files. Delete them before squash-merging the branch back into main.
+
+## Skills
+
+Everything is a skill. Skills are either atomic (do one thing) or composite (orchestrate other skills).
+
+### Pipeline skills
+
+| Skill | Type | Purpose |
+|-------|------|---------|
+| `forge` | atomic | Produce or revise an artefact |
+| `quench` | atomic | Run deterministic CLI checks |
+| `appraise` | atomic | Dispatch multiple appraisers, consolidate feedback |
+| `cycle` | composite | forge → quench → appraise → iterate |
+| `flow` | composite | Orchestrate cycles on a work branch |
+
+### Helper skills
+
+| Skill | Purpose |
+|-------|---------|
+| `init-foundry` | Scaffold the `foundry/` directory in your project |
+| `add-artefact-type` | Create a new artefact type with conflict and glob-overlap checks |
+| `add-law` | Create a new law with conflict detection |
+| `add-appraiser` | Create a new appraiser personality with semantic overlap checks |
+| `add-cycle` | Create a new cycle within a flow with dependency validation |
+| `add-flow` | Create a new flow definition |
+
+### Utility skills
+
+| Skill | Purpose |
+|-------|---------|
+| `sort` | Deterministic cycle router — determines and dispatches the next stage |
+| `hitl` | Human-in-the-loop intervention points |
+
+All helper skills are interactive — they walk you through the process, check for conflicts, and confirm before writing files.
+
+## Package structure
+
+```
+@really-knows-ai/foundry
+├── .opencode/
+│   └── plugins/
+│       └── foundry.js          # OpenCode plugin (registers skills)
+├── skills/                     # skill definitions (the pipeline)
+│   ├── forge/
+│   ├── quench/
+│   ├── appraise/
+│   ├── cycle/
+│   ├── flow/
+│   ├── init-foundry/
+│   ├── add-artefact-type/
+│   ├── add-law/
+│   ├── add-appraiser/
+│   ├── add-cycle/
+│   ├── add-flow/
+│   ├── sort/
+│   └── hitl/
+├── scripts/                    # validation support scripts
+├── docs/                       # concept docs and specs
+├── package.json
+└── README.md
+```
+
+## User project structure
+
+After running `init-foundry`, your project gets a `foundry/` directory:
+
+```
+your-project/
+├── foundry/
+│   ├── flows/                  # flow definitions
+│   ├── cycles/                 # cycle definitions
+│   ├── artefacts/              # artefact type definitions
+│   │   └── <type>/
+│   │       ├── definition.md
+│   │       ├── laws.md         # (optional) type-specific laws
+│   │       └── validation.md   # (optional) CLI checks
+│   ├── laws/                   # global laws
+│   └── appraisers/             # appraiser personalities
+├── opencode.json
+└── ...
+```
+
+## Design decisions
+
+### Everything is markdown
+
+Flow definitions, cycle definitions, artefact types, laws, appraiser personalities, skills — all markdown. Readable by humans, consumable by LLMs, versionable in git. No config files, no databases, no custom formats.
+
+### Skills are the pipeline
+
+No separate runner script. Composition happens via skills referencing other skills. The `flow` skill reads a flow definition and invokes the `cycle` skill. The `cycle` skill invokes `forge`, `quench`, and `appraise`. This keeps everything in one format.
+
+### WORK.md as shared state
+
+All communication between stages goes through WORK.md. No stage passes output directly to another. This gives a complete audit trail, makes the process resumable, and means any stage can be re-run independently.
+
+### Feedback as checklist items
+
+Feedback uses markdown checklists with `#validation` or `#law:<id>` tags. Human-readable, trivially parseable by an LLM, with lifecycle states expressed inline.
+
+### Wont-fix requires appraiser approval
+
+The generator can decline subjective feedback with a justification, but an appraiser must approve or reject that decision. This prevents silently ignoring feedback while allowing legitimate pushback.
+
+### Multi-model stage routing
+
+Cycle definitions specify which model each stage uses via a `models` map. The Foundry plugin auto-discovers available models and registers them as `foundry-*` sub-agents. Individual appraisers can override the cycle-level model. Resolution order: appraiser `model` → cycle `models.<stage>` → session default. Multiple personalities catch different issues. Consolidation is union with dedup — one appraiser flagging an issue is enough.
+
+### Input artefacts are read-only
+
+When a cycle reads from a previous cycle's output, those files cannot be modified. Enforced via git diff after every micro-commit. This prevents downstream cycles from corrupting upstream work.
+
+### Glob patterns must not overlap
+
+Two artefact types cannot have file patterns that match the same files. This is checked when creating new types and is a hard block — file modification enforcement can't determine ownership if patterns overlap.
+
+## License
+
+[MIT](LICENSE)

package/docs/concepts.md

@@ -0,0 +1,55 @@
+# Concepts
+
+Core concepts and how they relate.
+
+## Foundry Flow
+
+A foundry flow is the top-level unit of work. It is defined in `foundry/flows/` and lists the foundry cycles to execute in order. Starting a foundry flow creates a work branch and a WORK.md file. A foundry flow is complete when all its foundry cycles are done.
+
+## Foundry Cycle
+
+A foundry cycle is an iterative loop that produces a single artefact type. It is defined in `foundry/cycles/` and specifies:
+- An output artefact type (read-write)
+- Zero or more input artefact types (read-only, from previous foundry cycles)
+
+A foundry cycle runs: forge → quench → appraise, repeating until all feedback is resolved or the iteration limit is hit.
+
+## Stage
+
+The steps within a foundry cycle. Each stage is referenced using a `base:alias` format (e.g. `forge:write-haiku`) where the base is the stage type and the alias describes its role in that cycle.
+
+- Forge — produce or revise the artefact
+- Quench — run deterministic CLI checks
+- Appraise — subjective evaluation by multiple appraisers
+- HITL — human-in-the-loop checkpoint (see below)
+
+## Artefact type
+
+A definition of what kind of thing is being produced. Lives in `foundry/artefacts/<type>/` with:
+- `definition.md` — identity, file patterns, output location, prose description
+- `laws.md` — type-specific subjective evaluation criteria
+- `validation.md` — CLI commands for deterministic quench checks
+
+## Law
+
+A subjective pass/fail criterion. Global laws live in `foundry/laws/` (all files concatenated). Type-specific laws live in `foundry/artefacts/<type>/laws.md`. Each law has an identifier (its heading), used in feedback tags.
+
+## Appraiser
+
+An independent evaluator with a defined personality. Lives in `foundry/appraisers/`. Each appraiser can optionally specify a `model` to override the cycle-level appraise model. Model diversity is configured at the cycle level (via the `models` frontmatter map) and optionally per-appraiser. They can be assigned to specific artefact types or appraise everything.
+
+## WORK.md
+
+The transient shared state for a foundry flow. Created on the work branch, it tracks: where the foundry flow is (frontmatter cursor), what artefacts exist, and all feedback with its full lifecycle. See [work-spec.md](work-spec.md) for the full spec.
+
+## Feedback
+
+The communication mechanism between stages. Written as markdown checklist items in WORK.md with tags (`#validation` or `#law:<id>`). Follows a lifecycle: open → actioned/wont-fix → approved/rejected. See [work-spec.md](work-spec.md) for details.
+
+## HITL
+
+Human-in-the-loop checkpoint. A stage type that pauses the foundry cycle and requests human input before continuing. Configured per cycle by including a `hitl:alias` entry in the `stages` list. When a hitl stage runs, it presents the current artefact state to the human and collects feedback tagged `#hitl`. Like other feedback, hitl feedback follows the standard lifecycle (open → actioned → approved/rejected).
+
+## Micro commit
+
+Every stage ends with a commit. This enables file modification enforcement — the foundry cycle checks the git diff to ensure each stage only touched files it was allowed to.

package/docs/getting-started.md

@@ -0,0 +1,78 @@
+# Getting Started
+
+How to set up and run your first foundry flow.
+
+## Prerequisites
+
+- Git repository initialised
+- Node.js available (for validation scripts)
+- An AI coding tool that supports skills (OpenCode, Claude Code, Copilot CLI, etc.)
+
+## Step by step
+
+### 1. Define an artefact type
+
+Create a directory under `foundry/artefacts/` with three files:
+
+```
+foundry/artefacts/my-type/
+  definition.md    # what it is, file patterns, output location
+  laws.md          # subjective laws (optional)
+  validation.md    # CLI validation commands (optional)
+```
+
+Use the `init-foundry` skill to scaffold the `foundry/` directory, then use `add-artefact-type` to create your first artefact type interactively — or create the directory structure above manually.
+
+### 2. Write laws
+
+Add global laws to any `.md` file in `foundry/laws/`. Add type-specific laws to `foundry/artefacts/<type>/laws.md`.
+
+Each law is a `##` heading with: a description, what passing looks like, and what failing looks like.
+
+### 3. Define a foundry cycle
+
+Create a file in `foundry/cycles/` that specifies what artefact type the foundry cycle produces and what inputs it reads:
+
+```yaml
+---
+id: my-cycle
+name: My Cycle
+output: my-type
+inputs: []
+---
+```
+
+Cycles list their stages using `base:alias` format — e.g. `forge:write-haiku`, `quench:check-syllables`. The alias makes each stage's purpose clear when reading WORK.md. You can also include `hitl:alias` stages for human-in-the-loop checkpoints.
+
+### 4. Define a foundry flow
+
+Create a file in `foundry/flows/` that lists foundry cycles in order:
+
+```markdown
+---
+id: my-flow
+name: My Flow
+---
+
+# My Flow
+
+Description of what this flow produces.
+
+## Cycles
+
+1. my-cycle
+```
+
+### 5. Run the foundry flow
+
+Tell your AI tool to start the foundry flow. It will create a work branch, initialise WORK.md, and begin executing foundry cycles.
+
+## What happens during a foundry flow
+
+1. The foundry flow skill creates a branch and WORK.md
+2. For each foundry cycle:
+   - Forge produces the artefact
+   - Quench runs CLI commands (if defined)
+   - Appraise dispatches sub-agent appraisers against the laws
+   - If feedback exists, forge revises and the foundry cycle repeats
+3. When all foundry cycles complete, the human decides to merge, PR, or discard