workspace-maxxing 0.1.0

package/.agents/skills/workspace-maxxing/.workspace-templates/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/.agents/skills/workspace-maxxing/.workspace-templates/skills/architecture/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: architecture
+description: "Designs workspace structure, plans folder layout, and creates the build plan. Use when planning workspace structure, designing folder hierarchy, or after research phase."
+triggers: ["design workspace", "plan structure", "folder layout", "build plan"]
+---
+
+## Overview
+
+Design the workspace structure based on research findings. Architecture translates research into a concrete, buildable plan.
+
+## When to Use
+
+- Phase 2 of the hybrid flow (after research)
+- When research is complete and building is next
+- When restructuring an existing workspace
+
+## When Not to Use
+
+- Before research is complete (use research sub-skill)
+- During building itself (use scaffold.ts directly)
+- For minor structural tweaks (use direct file operations)
+
+## The Iron Law
+
+NO ARCHITECTURE WITHOUT RESEARCH
+NO BUILDING WITHOUT APPROVED PLAN
+NO SKIPPING USER APPROVAL
+NO AMBIGUOUS STAGE DEFINITIONS
+
+## Scope Guardrails
+
+- Design only the ICM workspace architecture (folders, routing, context contracts).
+- Plan markdown workflow artifacts per stage; do not design application runtime components.
+- Keep architecture outputs directly consumable by scaffold.ts for file-structured markdown folders.
+- Treat product implementation asks as workflow requirements captured in stage docs.
+
+## The Process
+
+1. **Review research findings** - Read the research sub-skill report.
+2. **Define stage folders** - Determine numbered folder structure (01-xxx, 02-xxx, and so on) for workflow execution.
+3. **Design routing table** - Plan CONTEXT.md routing for each stage.
+4. **Define SYSTEM.md** - Plan the folder map, rules, and tool inventory.
+5. **Plan CONTEXT.md content** - Define what each stage CONTEXT.md must contain and which markdown artifacts it must produce.
+6. **Create build plan** - Document the scaffold.ts command with all parameters.
+7. **Get approval** - Present the plan to the user before building.
+
+## Red Flags
+
+- Stage folders do not follow sequential numbering
+- Routing table does not reference all stages
+- SYSTEM.md plan is missing or incomplete
+- Build plan is missing scaffold.ts parameters
+- User approval is skipped before build
+- Plan includes backend/frontend/database implementation details instead of workspace structure
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I will adjust the structure while building" | Structure changes mid-build are expensive. Plan first. |
+| "This stage name is good enough" | Stage names affect routing. Be precise. |
+| "The user will understand without approval" | Unapproved plans produce unwanted results. Always present the plan. |
+
+## Sub-Skill Dispatch
+
+- `status = passed` (plan approved) -> `nextSkill = none` and main workflow runs scaffold.ts.
+- `status = failed` (plan incomplete or not approved) -> `nextSkill = none`.
+- `status = escalated` (blocking uncertainty) -> `nextSkill = none`.
+
+## Report Format
+
+```json
+{
+  "skill": "architecture",
+  "status": "passed",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "findings": ["Defined four sequential stages with explicit routing"],
+  "recommendations": ["Run scaffold.ts using the approved stage list"],
+  "metrics": {
+    "stagesPlanned": 4,
+    "toolsIdentified": 2
+  },
+  "nextSkill": "none"
+}
+```
+
+Allowed `status` values: `passed`, `failed`, `escalated`.
+
+Allowed `nextSkill` values: `none`.
+
+## Integration
+
+- Uses research output as architecture input.
+- Produces the approved plan consumed by scaffold.ts.
+

package/.agents/skills/workspace-maxxing/.workspace-templates/skills/fixer/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: fixer
+description: "Applies targeted fixes to failing test case outputs. Use when fixing failed worker outputs, improving low-scoring results, or addressing validator findings."
+triggers: ["fix failing test", "improve output", "address validation failure", "apply targeted fix"]
+---
+
+## Overview
+
+Read validator findings and original worker output, identify the root cause of failure, apply the minimal fix needed, and prepare the case for re-validation. Each fixer runs with fresh context.
+
+## When to Use
+
+- Dispatched by orchestrator in a fix loop
+- Validator identifies specific failures for a test case
+- Worker output is incomplete, incorrect, or misaligned with expectations
+
+## When Not to Use
+
+- Generating new output from scratch (use worker sub-skill)
+- Validating outputs (use validation sub-skill)
+- Redesigning workspace structure (use architecture sub-skill)
+
+## The Iron Law
+
+NO BLIND RETRIES
+NO COSMETIC FIXES
+NO FIXING WHAT IS NOT BROKEN
+NO CLAIMING FIX WITHOUT RE-VALIDATION
+
+## The Process
+
+1. **Read validator findings** - Load `batch-report.json` from the batch directory
+2. **Read original output** - Load `output.md` and `report.json` from `.agents/iteration/batch-<N>/<testCaseId>/`
+3. **Identify root cause** - Map each finding to a specific defect in the output
+4. **Apply minimal fix** - Change only what is needed to resolve each finding
+5. **Update output.md** - Write the fixed output for the same test case
+6. **Write report.json** - Structured JSON with `{skill, status, timestamp, testCaseId, batchId, findings, fixesApplied, recommendations, metrics, nextSkill}`
+7. **Dispatch validation** - Signal that the fix is ready for re-validation
+
+## External Runner Contract
+
+- Fixer execution in autonomous iteration is orchestrated via `--subagent-runner`.
+- Direct fixer dispatch must provide `--runner-command` with placeholders `{skill}`, `{workspace}`, `{batchId}`, `{testCaseId}`.
+- Runner output must be JSON and include `report.json` compatible fields:
+  - `skill`, `status`, `timestamp`, `findings`, `recommendations`, `metrics`, `nextSkill`
+- Missing/invalid runner output is a failure, not a simulated success path.
+- Use `.agents/iteration/runs/*.json` telemetry to debug command rendering and runner payload issues.
+
+## Agent-Driven Test-Case Generation (Required)
+
+- **Agent ownership:** Test-cases MUST be discovered and authored by an agent using the workspace context. Do not rely on hardcoded script-generated test cases.
+- **Where to write:** The agent must write the test-case bundle to `.agents/iteration/test-cases.json` inside the workspace before the orchestrator or validator dispatches workers. Validators and orchestrator flows will treat this file as the authoritative source of inputs for the iteration.
+- **Discovery guidance:** Agents should inspect repo files (SYSTEM.md, CONTEXT.md, stage CONTEXTs, user prompts, examples, and any domain files) to infer realistic inputs, edge cases, and acceptance criteria. Test-cases should reflect actual workspace intent and cover positive, negative, and boundary cases.
+- **Schema (minimal):** The file must be valid JSON and an array of objects with the following fields:
+
+```json
+[
+  {
+    "id": "tc-001",
+    "title": "Short descriptive title",
+    "input": {"type": "text", "payload": "..."},
+    "expected": {"criteria": ["..."], "matcher": "contains|equals|schema"},
+    "metadata": {"priority": "high|medium|low", "sourceHints": ["SYSTEM.md"]}
+  }
+]
+```
+
+- **Idempotence:** Agents may re-generate or refine the file across iterations, but each write must be complete (no partial artifacts) and timestamped inside the JSON if updated.
+- **Signal readiness:** After creating `.agents/iteration/test-cases.json` the agent should also write a single-line marker file `.agents/iteration/.test-cases-ready` to avoid race conditions with orchestrators reading stdout.
+
+## Enforcement Notes
+
+- **Validator contract:** The validation step is expected to check for `.agents/iteration/test-cases.json` when running in agent-driven mode and fail fast if missing or malformed. This ensures the orchestrator cannot fall back to hardcoded script cases.
+- **Orchestrator behavior:** When agent-driven mode is enabled, the orchestrator must prefer `.agents/iteration/test-cases.json` and should not call or rely on any built-in `generate-tests` script to produce authoritative inputs.
+- **Audit trail:** Agents should include a `generatedBy` and `timestamp` field in the test-cases file to aid debugging and reproducibility.
+
+## Anti-Rationalization Table
+
+| Thought | Reality |
+|---------|---------|
+| "I will just re-run the worker logic" | Blind retries do not fix root causes. Address the findings directly. |
+| "This looks better now" | Better is subjective. The fix must satisfy the validator criteria. |
+| "I will fix other things while I am here" | Scope creep adds risk. Fix only what was flagged. |
+| "The fix is obvious" | Obvious assumptions cause regressions. Tie every change to a finding. |
+| "I do not need to re-validate" | Unvalidated fixes are guesses. Always dispatch validation. |
+
+## Sub-Skill Dispatch
+
+- After fix applied -> validation sub-skill
+
+## Report Format
+
+```json
+{
+  "skill": "fixer",
+  "status": "passed|failed|escalated",
+  "timestamp": "2026-04-08T00:00:00Z",
+  "testCaseId": "tc-001",
+  "batchId": 1,
+  "findings": ["Missing expected acceptance criteria section"],
+  "fixesApplied": ["Added acceptance criteria section from validator recommendation"],
+  "recommendations": ["Run validation to confirm all findings are cleared"],
+  "metrics": {
+    "findingsAddressed": 1,
+    "fixesApplied": 1
+  },
+  "nextSkill": "validation"
+}
+```