aiwg 2026.7.23 → 2026.7.24

package/agentic/code/addons/agent-loop/templates/ralph-completion.md

@@ -0,0 +1,18 @@
+---
+name: ralph-completion
+description: Completion summary scaffold for an agent-loop iteration.
+---
+
+# Ralph Completion Template
+
+## Outcome
+
+{{outcome}}
+
+## Evidence
+
+{{evidence}}
+
+## Follow Up
+
+{{follow_up}}

package/agentic/code/addons/agent-loop/templates/ralph-task.md

@@ -0,0 +1,18 @@
+---
+name: ralph-task
+description: Task prompt scaffold for an agent-loop iteration.
+---
+
+# Ralph Task Template
+
+## Goal
+
+{{goal}}
+
+## Context
+
+{{context}}
+
+## Completion Criteria
+
+{{completion_criteria}}

package/agentic/code/addons/agentic-installer/README.md

@@ -69,23 +69,30 @@ recovery_procedures:
 ```
 
 ```bash
-# Validate
+# Generate starter runtime assets
+aiwg setup-generate --output setup.manifest.yaml
+
+# Validate for agentic runtime consumption
 aiwg setup-validate setup.manifest.yaml
 
-# Dry run
-aiwg setup-run --dry-run
+# Dry run without executing steps
+aiwg setup-run --manifest setup.manifest.yaml --dry-run
 
-# Execute
-aiwg setup-run
+# Execute only after the automation has reviewed the plan and has authorization
+aiwg setup-run --manifest setup.manifest.yaml --confirm
 ```
 
-## Skills
+## Agentic Runtime Commands
+
+These CLI entrypoints are for agents and automation. They are intentionally
+machine-oriented surfaces that make setup assets discoverable, validateable, and
+executable under explicit safety gates.
 
-| Skill | Description |
-|-------|-------------|
-| `setup-generate` | Generate a manifest from project context (README, package files) |
-| `setup-run` | Execute a manifest step by step with platform detection |
-| `setup-validate` | Validate a manifest against schema and run consistency checks |
+| Command | Backing skill | Description |
+|---------|---------------|-------------|
+| `setup-generate` | `setup-generate` | Generate starter manifest and script assets |
+| `setup-validate` | `setup-validate` | Validate a manifest against schema and consistency checks |
+| `setup-run` | `setup-run` | Validate, plan, and execute manifest steps with confirmation gates |
 
 ## Script Template Library
 

package/agentic/code/addons/agentic-installer/skills/setup-generate/SKILL.md

@@ -23,15 +23,20 @@ Generate a `setup.manifest.yaml` file for a project using the `setup.aiwg.io/v1`
 ### project-dir (positional, optional)
 Path to the project root. Defaults to `.`.
 
-### --from-readme (optional)
-Extract requirements from `README.md` or `INSTALL.md` in the project dir.
+### --output (optional)
+Manifest path to create. Default: `./setup.manifest.yaml`.
 
-### --from-existing (optional)
-Update an existing `setup.manifest.yaml` rather than creating from scratch.
+### --name (optional)
+Manifest `metadata.name`. Default: package name or project directory name.
 
-### --platforms (optional)
-Comma-separated list of target platforms: `linux,macos,windows,wsl2`.
-Default: `linux,macos`.
+### --type (optional)
+Install type: `user`, `developer`, or `ci`. Default: `developer`.
+
+### --platform (optional)
+Target platform: `linux`, `macos`, `windows`, or `docker`.
+
+### --force (optional)
+Overwrite existing generated manifest/script files.
 
 ### --type (optional)
 Install type to generate: `user`, `developer`, or `ci`.
@@ -54,7 +59,9 @@ Ask clarifying questions before generating.
    - Check for `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `Makefile`, etc.
    - Check for `README.md`, `INSTALL.md`, `docs/install.md`
    - Check for existing `setup.manifest.yaml`
-2. If `--from-readme`, parse installation instructions from readme
+2. Parse local project cues when they are available; the CLI entrypoint emits
+   a conservative starter manifest and leaves richer project-specific authoring
+   to the agent skill.
 3. If `--interactive`, ask:
    - What OSes must be supported?
    - What are the hard prerequisites (git, node, python version)?
@@ -80,8 +87,8 @@ Additional discovery steps for developer manifests:
 
 Build the manifest YAML following this priority order:
 
-1. **metadata block** — include `install_type` matching `--type` flag (default: `user`)
-2. **platform block** — from `--platforms` or detected by project type
+1. **metadata block** — include `install_type` matching `--type` flag (default: `developer`)
+2. **platform block** — from `--platform` or detected by project type
 3. **params block** — standard params: `INSTALL_DIR`, `BRANCH` (default: `main`); add `CONFIG_DIR` if a config step is needed
 4. **prerequisites block** — from project type (e.g., `node` for npm projects, `python3` for Python)
 5. **steps block** — construct from script templates:
@@ -213,21 +220,14 @@ Write the manifest to the appropriate path:
 
 Report:
 ```
-Generated: setup.dev.manifest.yaml
+Generated: setup.manifest.yaml
   Install type:  developer
-  Platform:      linux, macos
-  OS config:     docker-group (linux), inotify-watches (linux), xcode-cli-tools (macos)
-  Params:        INSTALL_DIR, LOCAL_DOMAIN [required], SSH_EMAIL [required]
-  Prerequisites: git, node (>=20), nvm, mkcert
-  Steps:         clone, install-deps, apply-docker-group, apply-inotify, configure-dev, verify-dev
-  Recovery:      full-reset
-  Scripts:       installer/scripts/dev/ (6 files)
-
-Note: 2 OS config steps require re-login to take effect. Installer will warn user.
-Note: 1 OS config step (xcode-cli-tools) triggers a GUI dialog on macOS.
-
-Validate with: aiwg setup-validate installer/setup.dev.manifest.yaml
-Run with:      aiwg setup-run installer/setup.dev.manifest.yaml
+  Platform:      linux
+  Steps:         setup
+  Scripts:       scripts/setup.sh
+
+Validate with: aiwg setup-validate --manifest setup.manifest.yaml
+Run with:      aiwg setup-run --manifest setup.manifest.yaml --dry-run
 ```
 
 ## Output File Structure

package/agentic/code/addons/agentic-installer/skills/setup-validate/SKILL.md

@@ -29,7 +29,7 @@ Path to schema file. Default: auto-located from AIWG installation.
 Fail on warnings in addition to errors.
 
 ### --fix (optional)
-Auto-fix simple issues (missing `id`, missing `depends_on` on sequential steps).
+Reserved for future safe autofixes. The current CLI validates and reports only.
 
 ## Validation Checks
 
@@ -122,17 +122,8 @@ Result: INVALID — fix errors before running
 
 ## Auto-fix (--fix)
 
-When `--fix` is passed, the skill will:
-1. Add `id` fields to any steps missing them (sequential: `step-1`, `step-2`, ...)
-2. Add obvious `depends_on` for sequential steps (each step depends on the previous)
-3. Print a diff of changes made
-
-It will NOT:
-- Change step types
-- Add or remove scripts
-- Modify param definitions
-- Add or remove `interactive_required` flags
-- Add or remove `os_config` entries
+`--fix` is reserved for future safe autofixes. The current agent-facing CLI
+validates and reports only; it does not mutate manifests.
 
 ## References
 

package/dist/src/artifacts/browser-export.js

@@ -326,6 +326,8 @@ export function recordTypeForEntry(entry, schemaVersion) {
             return "aiwg.command";
         case "rule":
             return "aiwg.rule";
+        case "schema":
+            return "aiwg.schema";
         case "behavior":
             return "aiwg.behavior";
         case "flow":

package/dist/src/artifacts/index-builder.js

@@ -132,6 +132,36 @@ function extractSummary(data, body) {
     const lines = body.split('\n').filter(l => l.trim() && !l.startsWith('#'));
     return lines.slice(0, 5).join(' ').slice(0, 500).trim();
 }
+function parseSchemaDoc(content, relativePath) {
+    if (!/\.(json|ya?ml)$/i.test(relativePath))
+        return null;
+    let parsed;
+    try {
+        parsed = /\.json$/i.test(relativePath) ? JSON.parse(content) : loadYaml(content);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const schema = parsed;
+    const title = typeof schema.title === 'string' && schema.title.trim()
+        ? schema.title.trim()
+        : undefined;
+    const id = typeof schema.$id === 'string' && schema.$id.trim()
+        ? schema.$id.trim()
+        : undefined;
+    const description = typeof schema.description === 'string' && schema.description.trim()
+        ? schema.description.trim().slice(0, 240)
+        : undefined;
+    const filename = path.basename(relativePath, path.extname(relativePath)).replace(/\.schema$/i, '');
+    return {
+        title: title ?? filename,
+        name: filename,
+        capability: description ?? (id ? `Schema definition for ${title ?? filename}` : undefined),
+        searchTerms: [id, title, filename, 'schema'].filter((term) => Boolean(term)),
+    };
+}
 /**
  * Determine SDLC phase from file path
  */
@@ -150,8 +180,6 @@ function inferPhase(filePath) {
  * always lands as `type: 'skill'` regardless of frontmatter.
  */
 function inferType(data, filePath) {
-    if (typeof data.type === 'string')
-        return data.type;
     // Normalize separators so matchers are cross-platform.
     const normalized = filePath.replace(/\\/g, '/');
     const basename = path.basename(filePath, path.extname(filePath)).toLowerCase();
@@ -179,7 +207,8 @@ function inferType(data, filePath) {
     const skipBasenames = new Set(['readme', 'rules-index', 'index']);
     const isMarkdown = /\.md$/i.test(filePath);
     const isTemplateAsset = TEMPLATE_INDEX_EXTENSIONS.some(ext => normalized.endsWith(ext));
-    if (!skipBasenames.has(basename) && (isMarkdown || isTemplateAsset)) {
+    const isSchemaAsset = /\.(json|ya?ml|md)$/i.test(filePath);
+    if (!skipBasenames.has(basename) && (isMarkdown || isTemplateAsset || isSchemaAsset)) {
         // Look at directory segments only (exclude the file itself).
         for (let i = segments.length - 2; i >= 0; i--) {
             const seg = segments[i];
@@ -215,6 +244,10 @@ function inferType(data, filePath) {
                     if (isMarkdown)
                         return 'rule';
                     break;
+                case 'schemas':
+                    if (isSchemaAsset)
+                        return 'schema';
+                    break;
                 case 'templates':
                     return 'template';
                 case 'behaviors':
@@ -228,6 +261,8 @@ function inferType(data, filePath) {
             }
         }
     }
+    if (typeof data.type === 'string')
+        return data.type;
     // Legacy SDLC artifact heuristics (existing behavior preserved).
     if (basename.startsWith('uc-') || basename.includes('use-case'))
         return 'use-case';
@@ -864,11 +899,12 @@ export async function buildIndex(cwd, options = {}) {
             const inferredType = inferType(data, relativePath);
             const physicalType = inferType({ ...data, type: undefined }, relativePath);
             const runbook = flow ? null : parseRunbookDoc(data, body, relativePath);
-            const title = flow?.name ?? extractTitle(data, body);
+            const schemaDoc = inferredType === 'schema' ? parseSchemaDoc(content, relativePath) : null;
+            const title = flow?.name ?? schemaDoc?.title ?? extractTitle(data, body);
             const phase = typeof data.phase === 'string' ? data.phase : inferPhase(relativePath);
             const type = flow?.type ?? (runbook ? 'runbook' : inferredType);
             const tags = flow ? flow.tags : (Array.isArray(data.tags) ? data.tags.map(String) : []);
-            const summary = flow?.description ?? runbook?.capability ?? extractSummary(data, body);
+            const summary = flow?.description ?? schemaDoc?.capability ?? runbook?.capability ?? extractSummary(data, body);
             const dependencies = extractMentions(content);
             // Discovery metadata (#1214, #1540, #1792) — meaningful for operational
             // AIWG artifact kinds. Kept undefined on document types so the index file
@@ -877,10 +913,10 @@ export async function buildIndex(cwd, options = {}) {
             // Declarative processes have no trigger phrases — they rely on their
             // capability and structure-aware search terms.
             const triggers = isDiscoverable && !flow ? extractTriggers(body, data) : undefined;
-            const capability = flow?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
+            const capability = flow?.capability ?? schemaDoc?.capability ?? runbook?.capability ?? (isDiscoverable ? extractCapability(data, body) : undefined);
             const kind = flow?.kind ?? runbook?.kind;
             const sourceType = runbook && physicalType !== 'runbook' ? physicalType : undefined;
-            const searchTerms = flow?.searchTerms ?? runbook?.searchTerms;
+            const searchTerms = flow?.searchTerms ?? schemaDoc?.searchTerms ?? runbook?.searchTerms;
             const kernel = data.kernel === true || data.kernel === 'true' ? true : undefined;
             // Script entrypoint metadata is meaningful for skills only (#1227).
             const script = type === 'skill' ? extractSkillScript(data) : undefined;
@@ -889,7 +925,7 @@ export async function buildIndex(cwd, options = {}) {
             // Canonical short name (#1233) — used by the scorer to floor exact-name
             // queries to 1.0 so hyphenated kernel-skill names like `aiwg-doctor`
             // remain searchable even when the rendered title strips the hyphen.
-            const name = flow ? flow.name : (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
+            const name = flow ? flow.name : schemaDoc?.name ?? (isDiscoverable ? extractCanonicalName(data, relativePath) : undefined);
             entry = {
                 path: relativePath,
                 type,

package/dist/src/artifacts/query-engine.js

@@ -174,7 +174,7 @@ const SCORE_STOPWORDS = new Set([
     'handle', 'handles', 'handling',
     // AIWG meta-type nouns — zero discriminating signal in a discover query
     'aiwg', 'skill', 'skills', 'agent', 'agents', 'command', 'commands',
-    'rule', 'rules', 'flow', 'flows', 'workflow', 'workflows',
+    'rule', 'rules', 'schema', 'schemas', 'flow', 'flows', 'workflow', 'workflows',
 ]);
 /**
  * Tokenize a query phrase into lowercased keywords for multi-word

package/dist/src/artifacts/types.js

@@ -24,6 +24,7 @@ export const OPERATIONAL_DISCOVERY_TYPES = [
     'agent',
     'command',
     'rule',
+    'schema',
     'flow',
     'runbook',
     'template',

package/dist/src/cli/handlers/index.js

@@ -38,6 +38,7 @@ import { packagesHandler } from './packages.js';
 import { marketplaceHandler } from './marketplace.js';
 import { initHandler } from './init.js';
 import { setupHandler } from './setup.js';
+import { setupGenerateHandler, setupRunHandler, setupValidateHandler } from './setup-manifest.js';
 import { runHandler } from './run.js';
 import { stewardHandler, stewardHandlers } from './steward.js';
 import { serveHandler } from './serve.js';
@@ -61,7 +62,7 @@ export {
 // Maintenance
 helpHandler, versionHandler, doctorHandler, updateHandler, refreshHandler, regenerateHandler, workspaceContextHandler, 
 // Framework management
-useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, issueHandler, issueAuditHandler, runHandler, 
+useHandler, listHandler, removeHandler, promoteHandler, installHandler, packagesHandler, marketplaceHandler, initHandler, setupHandler, setupGenerateHandler, setupRunHandler, setupValidateHandler, issueHandler, issueAuditHandler, runHandler, 
 // Project
 newBundleHandler, quickrefHandler, newProjectHandler, sessionHandler, sessionsHandler, 
 // Workspace
@@ -132,6 +133,9 @@ export const allHandlers = [
     newProjectHandler,
     initHandler,
     setupHandler,
+    setupGenerateHandler,
+    setupRunHandler,
+    setupValidateHandler,
     issueHandler,
     issueAuditHandler,
     runHandler,