npm - workspace-maxxing - Versions diffs - 0.4.0 → 0.6.0 - Mend

workspace-maxxing 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -1,186 +1,166 @@
-# workspace-maxxing
-An AI agent skill that builds ICM-compliant workspaces with invokable agents. The skill runs **inside your AI agent** and creates workspaces + agents on demand.
-## The Flow
-```
-1. Install: npx workspace-maxxing install
-2. Invoke in AI: @workspace-maxxing
-3. Ask: "Create a daily digest workspace"
-4. Skill builds: workspace + @daily-digest agent
-```
-## Quick Start
-```bash
-# Step 1: Install the skill to your project
-npx workspace-maxxing install
-# Step 2: In your AI agent, invoke the skill
-@workspace-maxxing
-# Step 3: Ask it to create something
-"Create a workspace for my daily news aggregator"
-```
-The skill will then:
-- Research your request
-- Design the workspace architecture
-- Build the ICM folder structure
-- Create an invokable agent inside
-- Run self-improvement on the agent
-- Deliver the complete workspace
-## What Gets Created
-When you ask `@workspace-maxxing` to create a workspace for "Daily Digest":
-```
-my-workspace/
-├── .agents/skills/daily-digest/  ← Invokable with @daily-digest
-│   ├── SKILL.md
-│   └── prompts/
-├── 01-input/
-├── 02-process/
-├── 03-output/
-├── SYSTEM.md
-└── CONTEXT.md
-```
-Now you can use `@daily-digest` to run that workflow!
-## Commands
-| Command | What It Does |
-|---------|-------------|
-| `npx workspace-maxxing install` | Install skill to current project |
-| `@workspace-maxxing` | Invoke in your AI agent |
-| `npx workspace-maxxing --opencode` | Install for specific platform |
-| `--stages` | "01-input,02-process,03-output" | Comma-separated stage names |
-| `--output` | "./workspace" | Output directory |
-| `--agent-name` | auto-generated (@workspace-name) | Custom agent name |
-| `--no-agent` | false | Create workspace without agent |
-| `--threshold` | 85 | Robustness threshold for agent iteration |
-| `--max-iterations` | 3 | Max improvement cycles |
-## What Gets Installed
-- `SKILL.md` (entry behavior and phase logic)
-- `.workspace-templates/` (SYSTEM/CONTEXT templates and scripts)
-- `scripts/` (scaffold, validate, dispatch, orchestrator, benchmark, etc.)
-## Agent Creation Workflow
-When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a daily digest agent"):
-1. **Parse the request** - Extract the agent purpose (e.g., "Daily Digest")
-2. **Create ICM workspace** - SYSTEM.md, CONTEXT.md, stage folders
-3. **Create invokable agent** - In `.agents/skills/@<purpose>/`
-4. **Run self-improvement loop**:
-   - Generate test cases (edge, empty, varied inputs)
-   - Validate agent handling
-   - Score robustness (0-100)
-   - If score < 85: improve prompts, retry
-   - Repeat until score >= 85 or max iterations (3)
-5. **Install agent** for platform (OpenCode/Claude/Copilot/Gemini)
-6. **Deliver** workspace with robust agent
-### Invoking the Created Agent
-After workspace is created, use `@` followed by the agent name:
-- **OpenCode**: `@daily-digest`
-- **Claude Code**: Via `.claude/skills/` directory
-- **Copilot**: Via `.github/copilot-instructions/`
-- **Gemini**: Via `.gemini/skills/` directory
-## 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
-```
-workspace-maxxing/
-├── src/
-│   ├── index.ts           # CLI entry point
-│   ├── install.ts        # Skill installation
-│   ├── agent-creator.ts  # Agent creation
-│   ├── agent-iterator.ts # Agent self-improvement
-│   ├── platforms/        # Platform installers
-│   └── scripts/          # Core scripts
-├── templates/
-│   ├── SKILL.md         # Main skill definition
-│   └── .workspace-templates/  # Workspace templates
-└── 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 License - see [LICENSE](LICENSE) file for details.
+# workspace-maxxing
+<p align="center">
+  <a href="https://www.npmjs.com/package/workspace-maxxing">
+    <img src="https://img.shields.io/npm/v/workspace-maxxing?style=flat&color=blue" alt="npm version">
+  </a>
+  <a href="https://github.com/ericjdz/workflow-maxxing/blob/master/LICENSE">
+    <img src="https://img.shields.io/npm/l/workspace-maxxing?style=flat&color=green" alt="MIT License">
+  </a>
+  <a href="https://github.com/ericjdz/workflow-maxxing">
+    <img src="https://img.shields.io/github/stars/ericjdz/workflow-maxxing?style=flat" alt="GitHub stars">
+  </a>
+</p>
+> An AI agent skill that builds ICM-compliant workspaces with invokable sub-agents. One command, complete workflow automation.
+## Why workspace-maxxing?
+Most AI agent workspaces are disorganized—context is scattered, prompts are vague, and workflows lack structure. **workspace-maxxing** solves this by:
+- **Creating structured workspaces** with ICM methodology (SYSTEM.md, CONTEXT.md, stage folders)
+- **Building autonomous agents** that you can invoke with `@agent-name`
+- **Self-improving agents** that validate and iterate until robust
+- **Automatic tool discovery** - checks available tools, installs missing ones
+## Quick Start
+```bash
+# 1. Install the skill to your project
+npx workspace-maxxing install
+# 2. In your AI agent, invoke the skill
+@workspace-maxxing
+# 3. Ask it to create something
+"Create a workspace for lead scraping"
+```
+The skill does everything else—creates folder structure, builds the agent, verifies tools, runs self-improvement.
+## What You Get
+When you ask for a "lead scraping" workspace:
+```
+lead-scraper/
+├── .agents/skills/lead-scraper/   ← Invokable with @lead-scraper
+│   ├── SKILL.md
+│   ├── prompts/
+│   └── config.json
+├── 01-input/                     ← Stage 1: Input
+├── 02-process/                    ← Stage 2: Processing
+├── 03-output/                    ← Stage 3: Output
+├── 00-meta/                      ← Metadata & tools
+├── SYSTEM.md                     ← Global rules
+└── CONTEXT.md                    ← Routing
+```
+Now use `@lead-scraper` to run that workflow anytime.
+## Features
+### 🎯 Agent Creation
+- Create invokable agents for any workflow
+- Agents self-improve until score ≥ 85
+- Built-in test case generation & validation
+### 🔧 Automatic Tool Discovery
+- Checks what native tools your AI agent has
+- Verifies tool accessibility with test runs
+- Installs missing MCPs or CLI tools automatically
+### 📁 ICM Workspace Structure
+- SYSTEM.md (global rules)
+- CONTEXT.md (routing)
+- Numbered stage folders (01-input, 02-process, 03-output)
+- 00-meta for tools & execution logs
+### 🔄 Multi-Platform Support
+| Platform | Installation |
+|----------|--------------|
+| OpenCode | `npx workspace-maxxing install` |
+| Claude Code | `npx workspace-maxxing --claude` |
+| GitHub Copilot | `npx workspace-maxxing --copilot` |
+| Gemini CLI | `npx workspace-maxxing --gemini` |
+## Commands
+### CLI Commands
+```bash
+# Install the skill
+npx workspace-maxxing install
+# Install for specific platform
+npx workspace-maxxing --opencode
+# Legacy commands (still work)
+npx workspace-maxxing init
+npx workspace-maxxing --create-workspace --workspace-name "My Project"
+```
+### In Your AI Agent
+When you invoke `@workspace-maxxing`, you can ask:
+| Request | Action |
+|---------|--------|
+| `"Build a workspace for X"` | Creates ICM workspace |
+| `"Create an agent for Y"` | Creates invokable @agent |
+| `"Validate my workspace"` | Checks ICM compliance |
+| `"Improve my workspace"` | Runs autonomous iteration |
+| `"Add tools for Z"` | Installs required tools |
+## Architecture
+```
+┌─────────────────────────────────────────────────────┐
+│ @workspace-maxxing (invoked by user)                │
+├─────────────────────────────────────────────────────┤
+│ 1. RESEARCH     → Analyze the request            │
+│ 2. TOOLING      → Discover & install tools       │
+│ 3. ARCHITECTURE → Design workspace structure      │
+│ 4. BUILD        → Create ICM folders & files      │
+│ 5. AGENT        → Build invokable @agent          │
+│ 6. ITERATE      → Self-improve until robust       │
+│ 7. DELIVER      → Complete workspace + agent      │
+└─────────────────────────────────────────────────────┘
+```
+## What's Inside
+| File/Folder | Purpose |
+|-------------|---------|
+| `SKILL.md` | Main skill definition |
+| `skills/` | Sub-skills (research, architecture, tooling, etc.) |
+| `scripts/` | Executable scripts (scaffold, validate, dispatch) |
+| `.workspace-templates/` | ICM workspace templates |
+## The Iron Law
+```
+NO BUILD WITHOUT PLAN
+NO PLAN WITHOUT RESEARCH
+NO TOOL DISCOVERY BEFORE AGENT DELIVERY
+NO IMPROVEMENT WITHOUT VALIDATION
+```
+## Requirements
+- Node.js 18+
+- npm or yarn
+- An AI agent (OpenCode, Claude, Copilot, or Gemini)
+## Contributing
+Contributions welcome! Please read the [contributing guide](CONTRIBUTING.md) first.
+## License
+MIT © [Eric Julian Deguzman](https://github.com/ericjdz)
+---
+<p align="center">Made with 🚀 by the workspace-maxxing team</p>

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "workspace-maxxing",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "npx-installable skill for AI agents to create structured workspaces using ICM methodology",
   "bin": {
     "workspace-maxxing": "dist/index.js"

package/templates/SKILL.md CHANGED Viewed

@@ -36,6 +36,33 @@ When you invoke `@workspace-maxxing`, you can ask:
 | "Improve my workspace" | Runs autonomous iteration |
 | "Add tools for Z" | Uses tooling sub-skill to install tools |
+**IMPORTANT - Tool Discovery Before Agent Delivery:**
+When creating ANY agent, ALWAYS do this FIRST:
+1. **Check native tools** - What capabilities does the AI agent already have?
+   - Playwright, puppeteer for browser automation?
+   - Curl, wget for HTTP requests?
+   - File system access?
+   - Database connections?
+2. **Verify tool accessibility** - Run a simple test to confirm tools work:
+   ```
+   Test: Can you make a simple HTTP request?
+   Test: Can you list files in the current directory?
+   Test: Can you execute a simple script?
+   ```
+3. **Install missing tools** - If native tools are insufficient:
+   - Use `/skill tooling` to install MCP servers
+   - Use `npm install` for CLI tools
+   - Document installed tools in `00-meta/tools.md`
+4. **Include tool instructions in agent prompts** - The created agent must know:
+   - What tools are available
+   - How to use them
+   - Any rate limits or constraints
 The skill will then execute the appropriate phases internally.
 ## Tool Discovery & Agent Harness
@@ -106,40 +133,51 @@ This skill provides a complete agent development harness:
 ## Agent Creation Workflow
-When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a daily digest agent"), follow this flow:
+When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a lead scraping agent"), follow this flow:
 ```
-1. Parse the request to extract the agent purpose (e.g., "Daily Digest")
-2. Create ICM workspace structure (SYSTEM.md, CONTEXT.md, stage folders)
-3. Create invokable agent in .agents/skills/@<purpose>/
-4. Run self-improvement loop on the agent
+1. Parse the request to extract the agent purpose (e.g., "Lead Scraper")
+2. DISCOVER TOOLS:
+   - Check what native tools are available in the AI agent (playwright, puppeteer, curl, etc.)
+   - Verify tool accessibility by running a simple test
+   - If native tools are insufficient, use tooling sub-skill to install MCPs or CLI tools
+   - Document tools in 00-meta/tools.md
+3. Create ICM workspace structure (SYSTEM.md, CONTEXT.md, stage folders)
+4. Create invokable agent in .agents/skills/@<purpose>/
+   - Include tool usage instructions in the agent prompts
+5. Run self-improvement loop on the agent
    - Generate test cases (edge, empty, varied inputs)
    - Validate agent handling
    - Score robustness (0-100)
    - If score < 85: improve prompts, retry
    - Repeat until score >= 85 or max iterations (3)
-5. Install agent for platform (OpenCode/Claude/Copilot/Gemini)
-6. Deliver workspace with robust agent
+6. Install agent for platform (OpenCode/Claude/Copilot/Gemini)
+7. Deliver workspace with robust agent
 ```
-### Agent Creation Example
+### Agent Creation with Tool Discovery Example
-User: "Create a daily digest agent"
+User: "Create an agent that scrapes internet data for leads"
 ```
--> Extract purpose: "Daily Digest"
--> DISCOVER TOOLS: Use /skill tooling to find relevant tools (e.g., RSS, web scraping, summarization)
+-> Extract purpose: "Lead Scraper"
+-> DISCOVER TOOLS:
+   - Check: Does agent have playwright? → Yes, test it works
+   - Check: Does agent have curl/wget? → Yes, verify accessible
+   - Check: Any MCP servers for scraping? → No, need to install
+   - Action: Run tooling sub-skill to install puppeteer or similar
+   - Verify: Test the tool with a simple request
 -> Create workspace with stages: 01-input, 02-process, 03-output
--> Create agent: @daily-digest in .agents/skills/daily-digest/
+-> Create agent: @lead-scraper with tool instructions in prompts
 -> Run iteration:
-   - Test: empty input -> fix prompts
-   - Test: special chars -> fix prompts
-   - Test: normal input -> validate
+   - Test: scraping a page -> works
+   - Test: handling empty pages -> handles gracefully
+   - Test: rate limiting -> respects limits
    - Score >= 85? Yes -> deliver
--> Agent is ready to invoke with @daily-digest
+-> Agent is ready to invoke with @lead-scraper
 ```
-**Key**: Always look for and leverage tools when creating agents or workspaces.
+**Tool Discovery is MANDATORY** - always check available tools, verify accessibility, and install missing tools before delivering the agent.
 ## When Not to Use
@@ -151,6 +189,7 @@ User: "Create a daily digest agent"
 NO BUILD WITHOUT PLAN
 NO PLAN WITHOUT RESEARCH
+NO TOOL DISCOVERY BEFORE AGENT DELIVERY
 NO IMPROVEMENT WITHOUT VALIDATION
 NO COMPLETION CLAIM WITHOUT VERIFICATION
 NO PRODUCT IMPLEMENTATION INSIDE WORKSPACE BUILDING MODE