workspace-maxxing 0.1.0

package/.agents/skills/workspace-maxxing/.workspace-templates/CONTEXT.md

@@ -0,0 +1,44 @@
+# Routing Table
+
+## How to Use This File
+
+Map each task to the smallest required context and avoid loading unrelated files.
+
+## Task Routing
+
+| When you need to... | Go to | Load |
+|---------------------|-------|------|
+| Understand workspace constraints | SYSTEM.md | Always loaded first |
+| Gather or validate inputs | 01-input/CONTEXT.md | Input stage contract |
+| Analyze, process, or draft | 02-process/CONTEXT.md | Processing stage contract |
+| Finalize and deliver outputs | 03-output/CONTEXT.md | Output stage contract |
+| Check available tools | 00-meta/tools.md | Tool inventory |
+
+## Loading Order
+
+1. SYSTEM.md (always)
+2. This root CONTEXT.md
+3. One relevant stage CONTEXT.md
+4. Only the task files needed for that stage
+
+## Scope Guardrails
+
+- Route domain goals into workflow design stages and markdown deliverables.
+- Do not scaffold backend, frontend, or runtime product repositories from this routing file.
+- Keep artifacts file-structured and markdown-first across numbered workflow folders.
+
+## Sequential Routing Contract
+
+- Route to the earliest incomplete stage listed in 00-meta/execution-log.md.
+- Do not skip forward to later stages while earlier stages remain incomplete.
+- Append handoff notes after each completed stage before advancing.
+
+## Stage Handoff Routing
+
+- 01-input -> 02-process when input completion criteria are met
+- 02-process -> 03-output when processing completion criteria are met
+- 03-output -> delivery and closure
+
+## Escalation
+
+Escalate when required sections are missing, routing is ambiguous, or dependencies conflict with stage order.

package/.agents/skills/workspace-maxxing/.workspace-templates/SYSTEM.md

@@ -0,0 +1,44 @@
+# System - Workspace Root
+
+## Role
+You are an AI assistant operating inside this workspace. Follow stage contracts, route tasks through stage contexts, and keep information canonical.
+
+## Folder Map
+
+| Folder | Purpose |
+|--------|---------|
+| 00-meta/ | Workspace configuration, tool inventory, session notes |
+| 01-input/ | Source materials, intake, and validation |
+| 02-process/ | Analysis, transformation, and drafting |
+| 03-output/ | Final deliverables and publication artifacts |
+
+## Workflow Rules
+
+1. Read this file first every session.
+2. Read root `CONTEXT.md` before loading stage files.
+3. Load only the stage context and task files required for the current step.
+4. Keep one canonical source for each fact; do not duplicate content across stages.
+
+## Scope Guardrails
+
+- Build workflow documentation, not product implementation code.
+- Keep stage outputs markdown-first (plans, checklists, prompts, routing notes).
+- If the user asks for product code, convert that into workflow requirements and stay inside ICM workspace scope.
+
+## Sequential Execution Protocol
+
+1. Complete stages in ascending numeric order.
+2. Record each completed stage in 00-meta/execution-log.md before routing onward.
+3. Do not generate final output until all prior stages are marked complete.
+
+## Stage Boundaries
+
+- Execute stages in order unless explicit handoff says otherwise.
+- One-way dependencies only: upstream -> downstream.
+- Downstream stages may reference upstream outputs, never reverse.
+
+## Tooling Policy
+
+- Tool inventory is tracked in `00-meta/tools.md`.
+- Check inventory before proposing installs.
+- Record approved tool changes in `00-meta/tools.md`.

package/.agents/skills/workspace-maxxing/.workspace-templates/references/anti-patterns.md

@@ -0,0 +1,16 @@
+# Anti-Patterns & Rationalization Prevention
+
+Common rationalizations agents use to skip steps, with reality checks.
+
+| Thought | Reality |
+|---------|---------|
+| "This workspace looks good enough" | Good enough is the enemy of excellent. Run validation. |
+| "I'll skip research and go straight to building" | Building without research produces generic, non-optimal workspaces. |
+| "The user didn't ask for tests" | Autonomous workflows require self-verification. Tests are mandatory. |
+| "I'll fix this later" | Later never comes. Fix it now or escalate. |
+| "This sub-skill doesn't apply here" | If there's a 1% chance it applies, dispatch it. |
+| "The score is fine" | Fine is not good. Target > 85. |
+| "I already validated this" | Validation is a snapshot. Re-validate after every change. |
+| "This prompt update is cosmetic" | Prompt quality directly impacts agent behavior. No cosmetic-only changes. |
+| "I'll do all phases at once" | Phases exist for a reason. Complete each before moving to the next. |
+| "The user will review anyway" | Autonomous means autonomous. Deliver quality without requiring human review. |

package/.agents/skills/workspace-maxxing/.workspace-templates/references/iron-laws.md

@@ -0,0 +1,26 @@
+# Iron Laws
+
+These rules are absolute. No exceptions. No rationalizations.
+
+## The Iron Laws of Workspace Building
+
+1. **NO BUILD WITHOUT PLAN** — Every workspace must have an approved architecture plan before scaffold.ts runs.
+
+2. **NO PLAN WITHOUT RESEARCH** — Architecture decisions must be informed by pattern research and context gathering.
+
+3. **NO IMPROVEMENT WITHOUT VALIDATION** — Never claim a workspace improved without running validate.ts before and after.
+
+4. **NO COMPLETION CLAIM WITHOUT VERIFICATION** — Run the full test suite and validation checks before declaring delivery.
+
+5. **NO SKIPPING PHASES** — The hybrid flow exists for a reason. Complete each phase before moving to the next.
+
+6. **NO SILENT FAILURES** — If a sub-skill fails, report it. Do not continue as if nothing happened.
+
+## Enforcement
+
+Before any action, ask: "Which iron law does this touch?" If the answer is "none," you're probably about to break one.
+
+Violation of any iron law requires immediate escalation to the human with:
+- Which law was violated
+- Why it was violated
+- Proposed fix

package/.agents/skills/workspace-maxxing/.workspace-templates/references/reporting-format.md

@@ -0,0 +1,52 @@
+# Sub-Skill Report Format
+
+All sub-skills return a structured JSON report. Use this exact format.
+
+## Report Structure
+
+```json
+{
+  "skill": "<skill-name>",
+  "status": "passed|failed|escalated",
+  "timestamp": "<ISO-8601 timestamp>",
+  "findings": [
+    "<specific finding 1>",
+    "<specific finding 2>"
+  ],
+  "recommendations": [
+    "<actionable recommendation 1>",
+    "<actionable recommendation 2>"
+  ],
+  "metrics": {
+    "<metric-name>": <value>,
+    "score": <0-100>,
+    "itemsChecked": <number>,
+    "itemsPassed": <number>
+  },
+  "nextSkill": "<next-skill-name>|none"
+}
+```
+
+## Field Descriptions
+
+- `skill`: Name of the sub-skill that generated this report
+- `status`: One of "passed", "failed", or "escalated"
+  - `passed`: All checks passed, no critical issues
+  - `failed`: One or more checks failed, actionable items exist
+  - `escalated`: Cannot proceed, requires human intervention
+- `timestamp`: ISO-8601 timestamp of report generation
+- `findings`: Array of specific observations (both positive and negative)
+- `recommendations`: Array of actionable next steps
+- `metrics`: Quantitative measurements from the sub-skill
+  - `score`: 0-100 quality score
+  - `itemsChecked`: Total items evaluated
+  - `itemsPassed`: Items that passed evaluation
+- `nextSkill`: Suggested next sub-skill to dispatch, or "none" if workflow is complete
+
+## Usage
+
+Print the report as JSON to stdout when the sub-skill completes:
+
+```bash
+echo '{"skill":"validation","status":"passed",...}'
+```

package/.agents/skills/workspace-maxxing/.workspace-templates/scripts/benchmark.ts

@@ -0,0 +1,171 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface StageBenchmark {
+  name: string;
+  raw: number;
+  weight: number;
+  weighted: number;
+}
+
+export interface BenchmarkResult {
+  workspace: string;
+  agent: string;
+  timestamp: string;
+  rawScore: number;
+  weightedScore: number;
+  stages: StageBenchmark[];
+  fixSuggestions: string[];
+  improvementPotential: boolean;
+}
+
+const STAGE_WEIGHTS: Record<string, number> = {
+  '01-ideation': 1.5,
+  '02-research': 1.3,
+  '03-architecture': 1.2,
+};
+
+const DEFAULT_WEIGHT = 1.0;
+const MAX_RAW_SCORE = 45;
+
+export function calculateBenchmark(workspacePath: string): BenchmarkResult {
+  const ws = path.resolve(workspacePath);
+  const stageFolders = getNumberedFolders(ws);
+
+  const stages: StageBenchmark[] = [];
+  let totalWeighted = 0;
+  let totalWeight = 0;
+
+  for (const folder of stageFolders) {
+    const weight = STAGE_WEIGHTS[folder] ?? DEFAULT_WEIGHT;
+    const raw = calculateStageRawScore(ws, folder);
+    const weighted = (raw / MAX_RAW_SCORE) * 100 * weight;
+
+    stages.push({ name: folder, raw, weight, weighted });
+    totalWeighted += weighted;
+    totalWeight += weight;
+  }
+
+  const weightedScore = totalWeight > 0 ? totalWeighted / totalWeight : 0;
+  const rawScore = stages.reduce((sum, s) => sum + s.raw, 0);
+
+  const fixSuggestions = stages
+    .filter((s) => s.raw < MAX_RAW_SCORE)
+    .map((s) => `Improve ${s.name}: current score ${s.raw}/${MAX_RAW_SCORE}`);
+
+  return {
+    workspace: path.basename(ws),
+    agent: 'unknown',
+    timestamp: new Date().toISOString(),
+    rawScore,
+    weightedScore: Math.min(Math.round(weightedScore), 100),
+    stages,
+    fixSuggestions,
+    improvementPotential: stages.some((s) => s.raw < MAX_RAW_SCORE),
+  };
+}
+
+export function formatBenchmarkTable(data: BenchmarkResult): string {
+  const lines: string[] = [];
+
+  lines.push(`\nBenchmark Report: ${data.workspace}`);
+  lines.push(`Agent: ${data.agent} | Timestamp: ${data.timestamp}`);
+  lines.push('');
+  lines.push(
+    padRight('Stage', 20) +
+    padRight('Raw', 8) +
+    padRight('Weight', 10) +
+    padRight('Weighted', 12)
+  );
+  lines.push('-'.repeat(50));
+
+  for (const stage of data.stages) {
+    lines.push(
+      padRight(stage.name, 20) +
+      padRight(String(stage.raw), 8) +
+      padRight(stage.weight.toFixed(1) + 'x', 10) +
+      padRight(stage.weighted.toFixed(1), 12)
+    );
+  }
+
+  lines.push('-'.repeat(50));
+  lines.push(
+    padRight('TOTAL', 20) +
+    padRight(String(data.rawScore), 8) +
+    padRight('', 10) +
+    padRight(data.weightedScore.toFixed(1), 12)
+  );
+  lines.push('');
+
+  if (data.fixSuggestions.length > 0) {
+    lines.push('Suggestions:');
+    for (const suggestion of data.fixSuggestions) {
+      lines.push(`  - ${suggestion}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+export function saveBenchmarkReport(workspacePath: string, data: BenchmarkResult): string {
+  const reportDir = path.join(workspacePath, '.workspace-benchmarks');
+  fs.mkdirSync(reportDir, { recursive: true });
+
+  const filename = `${data.workspace}-${data.timestamp.replace(/[:.]/g, '-')}.json`;
+  const filePath = path.join(reportDir, filename);
+
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2), 'utf-8');
+  return filePath;
+}
+
+function calculateStageRawScore(ws: string, folder: string): number {
+  const stageContextPath = path.join(ws, folder, 'CONTEXT.md');
+  let score = 0;
+
+  if (fs.existsSync(stageContextPath)) {
+    const content = fs.readFileSync(stageContextPath, 'utf-8');
+    if (content.toLowerCase().includes('purpose') || content.toLowerCase().includes('## purpose')) score += 4;
+    if (content.toLowerCase().includes('input')) score += 4;
+    if (content.toLowerCase().includes('output')) score += 4;
+    if (content.toLowerCase().includes('dependenc')) score += 3;
+    if (content.toLowerCase().includes('## success criteria') || content.toLowerCase().includes('success criteria')) score += 5;
+    if (content.toLowerCase().includes('## approach') || content.toLowerCase().includes('approach')) score += 5;
+    if (content.toLowerCase().includes('## risks') || content.toLowerCase().includes('risks')) score += 5;
+    if (content.toLowerCase().includes('## timeline') || content.toLowerCase().includes('timeline')) score += 5;
+    if (content.toLowerCase().includes('## resources') || content.toLowerCase().includes('resources')) score += 5;
+    if (content.toLowerCase().includes('## validation') || content.toLowerCase().includes('validation')) score += 5;
+  }
+
+  return Math.min(score, MAX_RAW_SCORE);
+}
+
+function getNumberedFolders(workspacePath: string): string[] {
+  if (!fs.existsSync(workspacePath)) return [];
+  const entries = fs.readdirSync(workspacePath, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isDirectory() && /^\d{2}-/.test(e.name) && e.name !== '00-meta')
+    .map((e) => e.name);
+}
+
+function padRight(str: string, length: number): string {
+  return str.padEnd(length);
+}
+
+if (require.main === module) {
+  const args = process.argv.slice(2);
+  const parseArg = (flag: string): string | undefined => {
+    const idx = args.indexOf(flag);
+    return idx !== -1 ? args[idx + 1] : undefined;
+  };
+
+  const workspace = parseArg('--workspace');
+
+  if (!workspace) {
+    console.error('Usage: node benchmark.ts --workspace <path>');
+    process.exit(1);
+  }
+
+  const result = calculateBenchmark(workspace);
+  console.log(formatBenchmarkTable(result));
+}