workspace-maxxing 0.1.0

package/.agents/skills/workspace-maxxing/scripts/validate.ts

@@ -0,0 +1,452 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface CheckResult {
+  name: string;
+  passed: boolean;
+  message: string;
+}
+
+export interface ValidationResult {
+  passed: boolean;
+  checks: CheckResult[];
+}
+
+const REQUIRED_SYSTEM_HEADINGS = [
+  '## Role',
+  '## Folder Map',
+  '## Workflow Rules',
+  '## Scope Guardrails',
+  '## Sequential Execution Protocol',
+  '## Stage Boundaries',
+  '## Tooling Policy',
+];
+
+const REQUIRED_ROOT_CONTEXT_HEADINGS = [
+  '## How to Use This File',
+  '## Task Routing',
+  '## Loading Order',
+  '## Scope Guardrails',
+  '## Sequential Routing Contract',
+  '## Stage Handoff Routing',
+  '## Escalation',
+];
+
+const REQUIRED_STAGE_CONTEXT_HEADINGS = [
+  '## Purpose',
+  '## Inputs',
+  '## Outputs',
+  '## Dependencies',
+  '## Required Evidence',
+  '## Completion Criteria',
+  '## Handoff',
+];
+
+const DISALLOWED_STAGE_SOURCE_EXTENSIONS = new Set([
+  '.ts',
+  '.tsx',
+  '.js',
+  '.jsx',
+  '.py',
+  '.java',
+  '.go',
+  '.rs',
+  '.cs',
+  '.cpp',
+  '.c',
+  '.rb',
+  '.php',
+  '.swift',
+  '.kt',
+  '.scala',
+]);
+
+export function validateWorkspace(workspacePath: string): ValidationResult {
+  const ws = path.resolve(workspacePath);
+  const checks: CheckResult[] = [];
+  const numberedFolders = getNumberedStageFolders(ws);
+
+  const systemMdPath = path.join(ws, 'SYSTEM.md');
+  const systemExists = fs.existsSync(systemMdPath);
+  checks.push({
+    name: 'SYSTEM.md exists',
+    passed: systemExists,
+    message: systemExists ? 'Found' : 'Missing',
+  });
+
+  if (systemExists) {
+    const systemContent = fs.readFileSync(systemMdPath, 'utf-8');
+    const hasFolderMap = systemContent.toLowerCase().includes('folder map');
+    checks.push({
+      name: 'SYSTEM.md contains folder map',
+      passed: hasFolderMap,
+      message: hasFolderMap ? 'Found' : 'Missing "folder map" reference',
+    });
+
+    addRequiredHeadingChecks('SYSTEM.md', systemContent, REQUIRED_SYSTEM_HEADINGS, checks);
+  } else {
+    checks.push({
+      name: 'SYSTEM.md contains folder map',
+      passed: false,
+      message: 'Cannot check — SYSTEM.md missing',
+    });
+
+    for (const heading of REQUIRED_SYSTEM_HEADINGS) {
+      checks.push({
+        name: `SYSTEM.md contains ${heading}`,
+        passed: false,
+        message: `Cannot check - SYSTEM.md missing`,
+      });
+    }
+  }
+
+  const contextMdPath = path.join(ws, 'CONTEXT.md');
+  const contextExists = fs.existsSync(contextMdPath);
+  checks.push({
+    name: 'CONTEXT.md exists at root',
+    passed: contextExists,
+    message: contextExists ? 'Found' : 'Missing',
+  });
+
+  if (contextExists) {
+    const contextContent = fs.readFileSync(contextMdPath, 'utf-8');
+    addRequiredHeadingChecks('CONTEXT.md', contextContent, REQUIRED_ROOT_CONTEXT_HEADINGS, checks);
+
+    const allReferenced = numberedFolders.every((folder) => contextContent.includes(`${folder}/CONTEXT.md`));
+    checks.push({
+      name: 'Root routing references all numbered stages',
+      passed: allReferenced,
+      message: allReferenced ? 'All numbered stages are routed' : 'Missing one or more numbered stage routes',
+    });
+
+    const enforcesSelectiveLoading =
+      /## Loading Order/i.test(contextContent)
+      && /SYSTEM\.md/i.test(contextContent)
+      && /Only the task files needed/i.test(contextContent);
+
+    checks.push({
+      name: 'Root loading order enforces selective loading',
+      passed: enforcesSelectiveLoading,
+      message: enforcesSelectiveLoading
+        ? 'Selective loading guidance found'
+        : 'Loading order lacks selective-loading guidance',
+    });
+  } else {
+    for (const heading of REQUIRED_ROOT_CONTEXT_HEADINGS) {
+      checks.push({
+        name: `CONTEXT.md contains ${heading}`,
+        passed: false,
+        message: 'Cannot check - CONTEXT.md missing',
+      });
+    }
+
+    checks.push({
+      name: 'Root routing references all numbered stages',
+      passed: false,
+      message: 'Cannot check - CONTEXT.md missing',
+    });
+    checks.push({
+      name: 'Root loading order enforces selective loading',
+      passed: false,
+      message: 'Cannot check - CONTEXT.md missing',
+    });
+  }
+
+  const executionLogPath = path.join(ws, '00-meta', 'execution-log.md');
+  const executionLogExists = fs.existsSync(executionLogPath);
+  checks.push({
+    name: '00-meta/execution-log.md exists',
+    passed: executionLogExists,
+    message: executionLogExists ? 'Found' : 'Missing',
+  });
+
+  if (executionLogExists) {
+    const executionLogContent = fs.readFileSync(executionLogPath, 'utf-8');
+    const hasStageChecklistHeading = /## Stage Checklist/i.test(executionLogContent);
+    checks.push({
+      name: 'Execution log contains stage checklist heading',
+      passed: hasStageChecklistHeading,
+      message: hasStageChecklistHeading ? 'Found' : 'Missing "## Stage Checklist" heading',
+    });
+
+    const hasAllStageChecklistEntries = numberedFolders.every((folder) => {
+      const pattern = new RegExp(`^\\s*-\\s*\\[[ xX]\\]\\s+${escapeRegExp(folder)}\\s*$`, 'm');
+      return pattern.test(executionLogContent);
+    });
+    checks.push({
+      name: 'Execution log references all numbered stages',
+      passed: hasAllStageChecklistEntries,
+      message: hasAllStageChecklistEntries
+        ? 'All numbered stages are present in checklist'
+        : 'Missing one or more numbered stage checklist entries',
+    });
+
+    const sequentialOrderValid = hasAllStageChecklistEntries
+      ? isExecutionChecklistSequential(executionLogContent, numberedFolders)
+      : false;
+    checks.push({
+      name: 'Execution log stage completion order is sequential',
+      passed: sequentialOrderValid,
+      message: sequentialOrderValid
+        ? 'Stage completion order is sequential'
+        : 'Found later stage marked complete before earlier stage',
+    });
+  } else {
+    checks.push({
+      name: 'Execution log contains stage checklist heading',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+    checks.push({
+      name: 'Execution log references all numbered stages',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+    checks.push({
+      name: 'Execution log stage completion order is sequential',
+      passed: false,
+      message: 'Cannot check - execution log missing',
+    });
+  }
+
+  for (const folder of numberedFolders) {
+    const contextPath = path.join(ws, folder, 'CONTEXT.md');
+    const exists = fs.existsSync(contextPath);
+    checks.push({
+      name: `${folder}/CONTEXT.md exists`,
+      passed: exists,
+      message: exists ? 'Found' : 'Missing',
+    });
+
+    if (exists) {
+      const content = fs.readFileSync(contextPath, 'utf-8');
+      const notEmpty = content.trim().length > 0;
+      checks.push({
+        name: `${folder}/CONTEXT.md is not empty`,
+        passed: notEmpty,
+        message: notEmpty ? `${content.trim().length} chars` : 'File is empty',
+      });
+
+      addRequiredHeadingChecks(`${folder}/CONTEXT.md`, content, REQUIRED_STAGE_CONTEXT_HEADINGS, checks);
+
+      const deps = extractStageRefs(extractDependenciesSection(content));
+      const currentNum = parseInt(folder.slice(0, 2), 10);
+      const pointsToLaterStage = deps.some((dep) => parseInt(dep.slice(0, 2), 10) > currentNum);
+
+      checks.push({
+        name: `${folder} dependencies do not point to later stages`,
+        passed: !pointsToLaterStage,
+        message: !pointsToLaterStage ? 'Dependency direction valid' : 'Found dependency on later-numbered stage',
+      });
+    } else {
+      for (const heading of REQUIRED_STAGE_CONTEXT_HEADINGS) {
+        checks.push({
+          name: `${folder}/CONTEXT.md contains ${heading}`,
+          passed: false,
+          message: 'Cannot check - CONTEXT.md missing',
+        });
+      }
+
+      checks.push({
+        name: `${folder} dependencies do not point to later stages`,
+        passed: false,
+        message: 'Cannot check - CONTEXT.md missing',
+      });
+    }
+
+    const disallowedFiles = findDisallowedStageSourceFiles(path.join(ws, folder));
+    checks.push({
+      name: `${folder} contains no product source code files`,
+      passed: disallowedFiles.length === 0,
+      message: disallowedFiles.length === 0
+        ? 'Only workflow documentation artifacts found'
+        : `Found source files: ${disallowedFiles.join(', ')}`,
+    });
+  }
+
+  const allFiles = getAllMarkdownFiles(ws);
+  const duplicateCheck = checkDuplicateContent(allFiles);
+  checks.push(duplicateCheck);
+
+  const passed = checks.every((c) => c.passed);
+
+  console.log(`\nValidation: ${ws}`);
+  console.log('='.repeat(50));
+  for (const check of checks) {
+    const icon = check.passed ? '✓' : '✗';
+    console.log(`  ${icon} ${check.name}: ${check.message}`);
+  }
+  console.log('='.repeat(50));
+  console.log(passed ? '✓ All checks passed' : '✗ Some checks failed');
+
+  return { passed, checks };
+}
+
+function getAllMarkdownFiles(dir: string): string[] {
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...getAllMarkdownFiles(fullPath));
+    } else if (entry.name.endsWith('.md')) {
+      results.push(fullPath);
+    }
+  }
+
+  return results;
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasHeading(content: string, heading: string): boolean {
+  return new RegExp(`^${escapeRegExp(heading)}\\s*$`, 'im').test(content);
+}
+
+function addRequiredHeadingChecks(
+  fileLabel: string,
+  content: string,
+  headings: string[],
+  checks: CheckResult[],
+): void {
+  for (const heading of headings) {
+    const found = hasHeading(content, heading);
+    checks.push({
+      name: `${fileLabel} contains ${heading}`,
+      passed: found,
+      message: found ? 'Found' : `Missing ${heading}`,
+    });
+  }
+}
+
+function checkDuplicateContent(files: string[]): CheckResult {
+  const MIN_DUPLICATE_LENGTH = 50;
+  const duplicates: string[] = [];
+
+  for (let i = 0; i < files.length; i++) {
+    for (let j = i + 1; j < files.length; j++) {
+      const contentA = fs.readFileSync(files[i], 'utf-8');
+      const contentB = fs.readFileSync(files[j], 'utf-8');
+
+      const linesA = contentA.split('\n');
+      const linesB = contentB.split('\n');
+
+      for (const lineA of linesA) {
+        const trimmed = lineA.trim();
+        if (trimmed.length > MIN_DUPLICATE_LENGTH) {
+          for (const lineB of linesB) {
+            if (lineB.trim() === trimmed) {
+              duplicates.push(trimmed.substring(0, 60) + '...');
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  if (duplicates.length > 0) {
+    return {
+      name: 'No duplicate content across files',
+      passed: false,
+      message: `Found ${duplicates.length} duplicate text block(s)`,
+    };
+  }
+
+  return {
+    name: 'No duplicate content across files',
+    passed: true,
+    message: 'No duplicates found',
+  };
+}
+
+function getNumberedStageFolders(workspacePath: string): string[] {
+  const entries = fs.readdirSync(workspacePath, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory() && /^\d{2}-/.test(entry.name) && entry.name !== '00-meta')
+    .map((entry) => entry.name);
+}
+
+function extractDependenciesSection(content: string): string {
+  const match = content.match(/## Dependencies\s*([\s\S]*?)(?=\n##\s|$)/i);
+  return match ? match[1] : '';
+}
+
+function extractStageRefs(content: string): string[] {
+  const refs = new Set<string>();
+  const regex = /(\d{2}-[A-Za-z0-9-_]+)/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(content)) !== null) {
+    refs.add(match[1]);
+  }
+
+  return Array.from(refs);
+}
+
+function isExecutionChecklistSequential(content: string, stages: string[]): boolean {
+  let foundUncheckedStage = false;
+
+  for (const stage of stages) {
+    const pattern = new RegExp(`^\\s*-\\s*\\[([ xX])\\]\\s+${escapeRegExp(stage)}\\s*$`, 'm');
+    const match = content.match(pattern);
+    if (!match) {
+      return false;
+    }
+
+    const isChecked = match[1].toLowerCase() === 'x';
+    if (!isChecked) {
+      foundUncheckedStage = true;
+      continue;
+    }
+
+    if (foundUncheckedStage) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+function findDisallowedStageSourceFiles(stageDir: string): string[] {
+  const disallowed: string[] = [];
+
+  const walk = (currentDir: string): void => {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        walk(fullPath);
+        continue;
+      }
+
+      const ext = path.extname(entry.name).toLowerCase();
+      if (DISALLOWED_STAGE_SOURCE_EXTENSIONS.has(ext)) {
+        disallowed.push(path.relative(stageDir, fullPath).replace(/\\/g, '/'));
+      }
+    }
+  };
+
+  walk(stageDir);
+
+  return disallowed;
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const workspaceIdx = args.indexOf('--workspace');
+  const workspace = workspaceIdx !== -1 ? args[workspaceIdx + 1] : undefined;
+
+  if (!workspace) {
+    console.error('Usage: node validate.ts --workspace <path>');
+    process.exit(1);
+  }
+
+  const result = validateWorkspace(workspace);
+  process.exit(result.passed ? 0 : 1);
+}

package/README.md

@@ -0,0 +1,144 @@
+# workspace-maxxing
+
+An installable skill package for AI coding agents that scaffolds, validates, and iterates on ICM-style workspaces with explicit workflow routing.
+
+## Why This Exists
+
+Most agent workspaces drift over time because prompts are underspecified and context loading is inconsistent. `workspace-maxxing` provides a repeatable workflow that generates structured `SYSTEM.md` and `CONTEXT.md` contracts, validates them, and improves them through autonomous iteration.
+
+## Features
+
+- Multi-agent install targets: OpenCode, Claude Code, GitHub Copilot, Gemini CLI
+- ICM workspace scaffolding with robust root and per-stage context contracts
+- Workflow-aware validation (routing coverage, stage dependency direction, selective loading)
+- Batched autonomous iteration via orchestrator + worker/fixer loops
+- Built-in test-case generation and weighted benchmarking
+
+## Requirements
+
+- Node.js 18+
+- `npx` available in your shell
+
+## Install
+
+```bash
+# OpenCode (default target)
+npx workspace-maxxing --opencode
+
+# Claude Code
+npx workspace-maxxing --claude
+
+# GitHub Copilot
+npx workspace-maxxing --copilot
+
+# Gemini CLI
+npx workspace-maxxing --gemini
+```
+
+### Install Targets
+
+| Target | Flag | Install Path |
+|---|---|---|
+| OpenCode | `--opencode` | `.agents/skills/workspace-maxxing/` |
+| Claude Code | `--claude` | `.claude/skills/` |
+| GitHub Copilot | `--copilot` | `.github/copilot-instructions/` |
+| Gemini CLI | `--gemini` | `.gemini/skills/` |
+
+## Quick Start
+
+1. Install to your preferred target with `npx workspace-maxxing --<target>`.
+2. Open a new agent session.
+3. Invoke the `workspace-maxxing` skill.
+4. Approve the proposed workflow structure.
+5. Let the agent scaffold, validate, and iterate until quality gates pass.
+
+## What Gets Installed
+
+- `SKILL.md` (entry behavior and phase logic)
+- `.workspace-templates/` (SYSTEM/CONTEXT templates and scripts)
+- `scripts/` (scaffold, validate, dispatch, orchestrator, benchmark, etc.)
+
+## Workflow Model
+
+The skill follows a phased flow:
+
+1. Research
+2. Architecture
+3. Build (scaffold workspace)
+4. Validate
+5. Autonomous iteration (batched worker/fixer loops)
+6. Deliver
+
+This is designed to keep prompt structure, execution order, and handoffs explicit.
+
+## Sub-Agent Runner Contract
+
+Worker/fixer execution is external-runner-driven in strict mode. Configure orchestrator with `--subagent-runner` (or `WORKSPACE_MAXXING_SUBAGENT_RUNNER`) using placeholders:
+
+```bash
+node scripts/orchestrator.ts --workspace ./workspace --subagent-runner "<runner-command> {skill} {workspace} {batchId} {testCaseId}"
+```
+
+Contract details:
+
+- `worker/fixer` require an external runner command.
+- Runner output must be JSON containing: `skill`, `status`, `timestamp`, `findings`, `recommendations`, `metrics`, `nextSkill`.
+- Missing/invalid payloads are treated as failures (no simulated completion).
+- Telemetry is written under `.agents/iteration/runs/` for troubleshooting.
+
+## Included Script Surface
+
+Run these from the installed skill directory (for example, `.agents/skills/workspace-maxxing/` in OpenCode).
+
+| Script | Purpose | Example |
+|---|---|---|
+| `scaffold.ts` | Create an ICM workspace from a stage plan | `node scripts/scaffold.ts --name "my-flow" --stages "01-input,02-process,03-output" --output ./workspace` |
+| `validate.ts` | Validate workspace structure and routing rules | `node scripts/validate.ts --workspace ./workspace` |
+| `generate-tests.ts` | Generate stage-based test cases | `node scripts/generate-tests.ts --workspace ./workspace --output ./tests.json` |
+| `dispatch.ts` | Dispatch sub-skills (single or parallel) | `node scripts/dispatch.ts --skill research --workspace ./workspace` |
+| `orchestrator.ts` | Run batched autonomous iteration | `node scripts/orchestrator.ts --workspace ./workspace --batch-size 3 --score-threshold 85 --subagent-runner "<runner>"` |
+| `benchmark.ts` | Compute weighted benchmark score | `node scripts/benchmark.ts --workspace ./workspace` |
+| `install-tool.ts` | Install a tool and update inventory | `node scripts/install-tool.ts --tool "pdf-lib" --manager npm --workspace ./workspace` |
+| `iterate.ts` | Legacy single-loop iteration path | `node scripts/iterate.ts --workspace ./workspace --max-retries 3` |
+
+## ICM Layers
+
+Based on the Interpretable Context Methodology (ICM):
+
+- Layer 0: `SYSTEM.md` (global rules)
+- Layer 1: root `CONTEXT.md` (routing)
+- Layer 2: stage `CONTEXT.md` files (contracts)
+- Layer 3: selective task artifacts
+
+Reference: [Interpretable Context Methodology paper](https://arxiv.org/abs/2603.16021)
+
+## Local Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Project Layout
+
+```text
+src/
+	index.ts
+	install.ts
+	scripts/
+templates/
+	SKILL.md
+tests/
+```
+
+## Contributing
+
+1. Fork and create a feature branch.
+2. Add or update tests for behavior changes.
+3. Run `npm run build` and `npm test`.
+4. Open a PR with context on workflow impact.
+
+## License
+
+MIT

package/dist/agent-creator.d.ts

@@ -0,0 +1,9 @@
+export interface AgentOptions {
+    name: string;
+    purpose: string;
+    workspacePath: string;
+    platforms?: string[];
+}
+export declare function generateAgentName(purpose: string): string;
+export declare function createAgent(options: AgentOptions): void;
+//# sourceMappingURL=agent-creator.d.ts.map

package/dist/agent-creator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-creator.d.ts","sourceRoot":"","sources":["../src/agent-creator.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAUzD;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAoCvD"}