workspace-maxxing

About

workspace-maxxing was born from a simple frustration: every AI workflow project started the same way—messy prompts, scattered context, and outputs that were impossible to reproduce.

I built this tool to enforce structure without killing creativity. The ICM methodology provided the framework, but the CLI makes it actionable. Now a single command scaffolds a complete workflow workspace with numbered stages, context contracts, and an invokable agent ready for iteration.

If you've ever struggled to get an AI to follow a consistent process, or if your prompts have drifted so far from the original intent that debugging feels impossible—this tool is for you.

---

Build structured, interpretable AI workflow workspaces and invokable agents from one command.

workspace-maxxing is an npx-installable CLI + skill package that helps you:

• Scaffold ICM-style workspace folders
• Install the workspace-maxxing skill into your agent environment
• Generate an invokable agent for your workflow
• Validate and iterate toward robust outputs

What Is workspace-maxxing?

workspace-maxxing turns vague requests like "build me a lead gen workflow" into a concrete, file-structured workspace with stage boundaries and context contracts.

Instead of throwing everything into one giant prompt, it creates a staged workflow with:

• SYSTEM.md for global rules
• Root CONTEXT.md for routing
• Numbered stage folders for execution order
• 00-meta/ for execution log and tool inventory
• Generated agent prompts and configuration

Why Use It?

Use workspace-maxxing when you want workflows that are easier to debug, review, and repeat.

1. Better control over agent behavior: numbered stages and explicit context files reduce prompt drift.
2. Easier review and handoff: outputs live in plain files, so humans can inspect and edit between stages.
3. Repeatable execution: the same structure can run new input with less re-prompting.
4. Cross-platform agent install: supports OpenCode, Claude Code, GitHub Copilot, and Gemini CLI targets.
5. Built-in quality loop: includes validation, test generation, benchmark scoring, and fix retries.

Methodology Basis (ICM)

This project is based in part on Interpratable Context Methodology (ICM) including folder-structure conventions such as numbered stage folders, stage contracts, selective context loading, and file-based handoffs.

Attribution:

• Jake Van Clief's ICM framework and conventions (RinDig repository)
• The broader ICM five-layer folder architecture described in public ICM template work

Relevant reference:

• https://arxiv.org/html/2603.16021v2

workspace-maxxing adapts those ideas to this CLI-driven layout:

workspace/
  SYSTEM.md
  CONTEXT.md
  00-meta/
    tools.md
    execution-log.md
  01-input/
    CONTEXT.md
  02-process/
    CONTEXT.md
  03-output/
    CONTEXT.md

Quick Start

1) Install the skill

npx workspace-maxxing init

For other platforms:

npx workspace-maxxing --claude
npx workspace-maxxing --copilot
npx workspace-maxxing --gemini

Then invoke in your AI session:

@workspace-maxxing
Create a daily digest workflow for AI news.

2) Create a full workspace plus agent directly

npx workspace-maxxing init --workspace-name "Daily Digest"

Common options:

• --workspace-name <name>
• --stages <comma-separated-stages>
• --output <path>
• --agent-name <name>
• --no-agent
• --threshold <score> (default: 85)
• --max-iterations <n> (default: 3)

Example:

npx workspace-maxxing init \
  --workspace-name "Lead Pipeline" \
  --stages "01-intake,02-enrich,03-output" \
  --output "./lead-workspace"

Use Cases

After install, talk to @workspace-maxxing in plain language:

• "Build a workspace for weekly product analytics reports"
• "Create an agent for PR review triage"
• "Validate this workspace"
• "Improve this workspace until robust"
• "Create a content pipeline for newsletters"
• "Set up a customer-support triage workflow"

The skill internally routes through specialized sub-skills such as:

• research
• architecture
• tooling
• validation
• worker
• fixer
• iteration

Onboarding

Use this first-run flow when setting up workspace-maxxing in a new repo:

1. Install the skill for your environment (install, --claude, --copilot, or --gemini).
2. Start your AI session and invoke @workspace-maxxing.
3. Describe the workflow goal in one sentence.
4. Review generated files (SYSTEM.md, CONTEXT.md, stage folders, and 00-meta/).
5. Run validation or iteration to improve robustness before regular use.

CLI Commands

# Help
npx workspace-maxxing --help

# Install skill (OpenCode target)
npx workspace-maxxing install

# Install skill for specific target
npx workspace-maxxing --opencode
npx workspace-maxxing --claude
npx workspace-maxxing --copilot
npx workspace-maxxing --gemini

# Create workspace (+ agent by default)
npx workspace-maxxing init

Local Development

From this repository:

npm install
npm run build
npm test

Run built CLI directly:

node dist/index.js init --workspace-name "Test Workspace"

If you want to test as a local package before publish:

npm pack
npx --yes --package ./workspace-maxxing-<version>.tgz workspace-maxxing install

Requirements

• Node.js 18+
• npm
• An AI agent environment (OpenCode, Claude Code, GitHub Copilot, or Gemini CLI)

License

MIT