workspace-maxxing 0.5.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 (2) hide show
  1. package/README.md +166 -205
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,205 +1,166 @@
1
- # workspace-maxxing
2
-
3
- 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.
4
-
5
- ## The Flow
6
-
7
- ```
8
- 1. Install: npx workspace-maxxing install
9
- 2. Invoke in AI: @workspace-maxxing
10
- 3. Ask: "Create a daily digest workspace"
11
- 4. Skill builds: workspace + @daily-digest agent
12
- ```
13
-
14
- ## Quick Start
15
-
16
- ```bash
17
- # Step 1: Install the skill to your project
18
- npx workspace-maxxing install
19
-
20
- # Step 2: In your AI agent, invoke the skill
21
- @workspace-maxxing
22
-
23
- # Step 3: Ask it to create something
24
- "Create a workspace for my daily news aggregator"
25
- ```
26
-
27
- The skill will then:
28
- - Research your request
29
- - Design the workspace architecture
30
- - Build the ICM folder structure
31
- - Create an invokable agent inside
32
- - Run self-improvement on the agent
33
- - Deliver the complete workspace
34
-
35
- ## What Gets Created
36
-
37
- When you ask `@workspace-maxxing` to create a workspace for "Daily Digest":
38
-
39
- ```
40
- my-workspace/
41
- ├── .agents/skills/daily-digest/ ← Invokable with @daily-digest
42
- │ ├── SKILL.md
43
- │ └── prompts/
44
- ├── 01-input/
45
- ├── 02-process/
46
- ├── 03-output/
47
- ├── SYSTEM.md
48
- └── CONTEXT.md
49
- ```
50
-
51
- Now you can use `@daily-digest` to run that workflow!
52
-
53
- ## Tool Discovery (Automatic)
54
-
55
- When you ask `@workspace-maxxing` to create an agent (e.g., "lead scraper"), it **automatically**:
56
-
57
- 1. **Checks available tools** - What does the AI agent already have?
58
- 2. **Verifies accessibility** - Runs a test to confirm tools work
59
- 3. **Installs missing tools** - Uses tooling sub-skill if needed
60
- 4. **Includes in agent** - Tool instructions in the created agent's prompts
61
-
62
- Example for "lead scraper":
63
- ```
64
- → Check: playwright available? test it
65
- → Check: curl available? verify
66
- → Missing: puppeteer MCP → install it
67
- → Test: can we scrape a page? → yes
68
- → Create @lead-scraper with tool instructions
69
- → Deliver
70
- ```
71
-
72
- ## Commands
73
-
74
- | Command | What It Does |
75
- |---------|-------------|
76
- | `npx workspace-maxxing install` | Install skill to current project |
77
- | `@workspace-maxxing` | Invoke in your AI agent |
78
- | `npx workspace-maxxing --opencode` | Install for specific platform |
79
- | `--stages` | "01-input,02-process,03-output" | Comma-separated stage names |
80
- | `--output` | "./workspace" | Output directory |
81
- | `--agent-name` | auto-generated (@workspace-name) | Custom agent name |
82
- | `--no-agent` | false | Create workspace without agent |
83
- | `--threshold` | 85 | Robustness threshold for agent iteration |
84
- | `--max-iterations` | 3 | Max improvement cycles |
85
-
86
- ## What Gets Installed
87
-
88
- - `SKILL.md` (entry behavior and phase logic)
89
- - `.workspace-templates/` (SYSTEM/CONTEXT templates and scripts)
90
- - `scripts/` (scaffold, validate, dispatch, orchestrator, benchmark, etc.)
91
-
92
- ## Agent Creation Workflow
93
-
94
- When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a daily digest agent"):
95
-
96
- 1. **Parse the request** - Extract the agent purpose (e.g., "Daily Digest")
97
- 2. **Create ICM workspace** - SYSTEM.md, CONTEXT.md, stage folders
98
- 3. **Create invokable agent** - In `.agents/skills/@<purpose>/`
99
- 4. **Run self-improvement loop**:
100
- - Generate test cases (edge, empty, varied inputs)
101
- - Validate agent handling
102
- - Score robustness (0-100)
103
- - If score < 85: improve prompts, retry
104
- - Repeat until score >= 85 or max iterations (3)
105
- 5. **Install agent** for platform (OpenCode/Claude/Copilot/Gemini)
106
- 6. **Deliver** workspace with robust agent
107
-
108
- ### Invoking the Created Agent
109
-
110
- After workspace is created, use `@` followed by the agent name:
111
-
112
- - **OpenCode**: `@daily-digest`
113
- - **Claude Code**: Via `.claude/skills/` directory
114
- - **Copilot**: Via `.github/copilot-instructions/`
115
- - **Gemini**: Via `.gemini/skills/` directory
116
-
117
- ## Workflow Model
118
-
119
- The skill follows a phased flow:
120
-
121
- 1. Research
122
- 2. Architecture
123
- 3. Build (scaffold workspace)
124
- 4. Validate
125
- 5. Autonomous iteration (batched worker/fixer loops)
126
- 6. Deliver
127
-
128
- This is designed to keep prompt structure, execution order, and handoffs explicit.
129
-
130
- ## Sub-Agent Runner Contract
131
-
132
- Worker/fixer execution is external-runner-driven in strict mode. Configure orchestrator with `--subagent-runner` (or `WORKSPACE_MAXXING_SUBAGENT_RUNNER`) using placeholders:
133
-
134
- ```bash
135
- node scripts/orchestrator.ts --workspace ./workspace --subagent-runner "<runner-command> {skill} {workspace} {batchId} {testCaseId}"
136
- ```
137
-
138
- Contract details:
139
-
140
- - `worker/fixer` require an external runner command.
141
- - Runner output must be JSON containing: `skill`, `status`, `timestamp`, `findings`, `recommendations`, `metrics`, `nextSkill`.
142
- - Missing/invalid payloads are treated as failures (no simulated completion).
143
- - Telemetry is written under `.agents/iteration/runs/` for troubleshooting.
144
-
145
- ## Included Script Surface
146
-
147
- Run these from the installed skill directory (for example, `.agents/skills/workspace-maxxing/` in OpenCode).
148
-
149
- | Script | Purpose | Example |
150
- |---|---|---|
151
- | `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` |
152
- | `validate.ts` | Validate workspace structure and routing rules | `node scripts/validate.ts --workspace ./workspace` |
153
- | `generate-tests.ts` | Generate stage-based test cases | `node scripts/generate-tests.ts --workspace ./workspace --output ./tests.json` |
154
- | `dispatch.ts` | Dispatch sub-skills (single or parallel) | `node scripts/dispatch.ts --skill research --workspace ./workspace` |
155
- | `orchestrator.ts` | Run batched autonomous iteration | `node scripts/orchestrator.ts --workspace ./workspace --batch-size 3 --score-threshold 85 --subagent-runner "<runner>"` |
156
- | `benchmark.ts` | Compute weighted benchmark score | `node scripts/benchmark.ts --workspace ./workspace` |
157
- | `install-tool.ts` | Install a tool and update inventory | `node scripts/install-tool.ts --tool "pdf-lib" --manager npm --workspace ./workspace` |
158
- | `iterate.ts` | Legacy single-loop iteration path | `node scripts/iterate.ts --workspace ./workspace --max-retries 3` |
159
-
160
- ## ICM Layers
161
-
162
- Based on the Interpretable Context Methodology (ICM):
163
-
164
- - Layer 0: `SYSTEM.md` (global rules)
165
- - Layer 1: root `CONTEXT.md` (routing)
166
- - Layer 2: stage `CONTEXT.md` files (contracts)
167
- - Layer 3: selective task artifacts
168
-
169
- Reference: [Interpretable Context Methodology paper](https://arxiv.org/abs/2603.16021)
170
-
171
- ## Local Development
172
-
173
- ```bash
174
- npm install
175
- npm run build
176
- npm test
177
- ```
178
-
179
- ## Project Layout
180
-
181
- ```
182
- workspace-maxxing/
183
- ├── src/
184
- │ ├── index.ts # CLI entry point
185
- │ ├── install.ts # Skill installation
186
- │ ├── agent-creator.ts # Agent creation
187
- │ ├── agent-iterator.ts # Agent self-improvement
188
- │ ├── platforms/ # Platform installers
189
- │ └── scripts/ # Core scripts
190
- ├── templates/
191
- │ ├── SKILL.md # Main skill definition
192
- │ └── .workspace-templates/ # Workspace templates
193
- └── tests/
194
- ```
195
-
196
- ## Contributing
197
-
198
- 1. Fork and create a feature branch.
199
- 2. Add or update tests for behavior changes.
200
- 3. Run `npm run build` and `npm test`.
201
- 4. Open a PR with context on workflow impact.
202
-
203
- ## License
204
-
205
- MIT License - see [LICENSE](LICENSE) file for details.
1
+ # workspace-maxxing
2
+
3
+ <p align="center">
4
+ <a href="https://www.npmjs.com/package/workspace-maxxing">
5
+ <img src="https://img.shields.io/npm/v/workspace-maxxing?style=flat&color=blue" alt="npm version">
6
+ </a>
7
+ <a href="https://github.com/ericjdz/workflow-maxxing/blob/master/LICENSE">
8
+ <img src="https://img.shields.io/npm/l/workspace-maxxing?style=flat&color=green" alt="MIT License">
9
+ </a>
10
+ <a href="https://github.com/ericjdz/workflow-maxxing">
11
+ <img src="https://img.shields.io/github/stars/ericjdz/workflow-maxxing?style=flat" alt="GitHub stars">
12
+ </a>
13
+ </p>
14
+
15
+ > An AI agent skill that builds ICM-compliant workspaces with invokable sub-agents. One command, complete workflow automation.
16
+
17
+ ## Why workspace-maxxing?
18
+
19
+ Most AI agent workspaces are disorganized—context is scattered, prompts are vague, and workflows lack structure. **workspace-maxxing** solves this by:
20
+
21
+ - **Creating structured workspaces** with ICM methodology (SYSTEM.md, CONTEXT.md, stage folders)
22
+ - **Building autonomous agents** that you can invoke with `@agent-name`
23
+ - **Self-improving agents** that validate and iterate until robust
24
+ - **Automatic tool discovery** - checks available tools, installs missing ones
25
+
26
+ ## Quick Start
27
+
28
+ ```bash
29
+ # 1. Install the skill to your project
30
+ npx workspace-maxxing install
31
+
32
+ # 2. In your AI agent, invoke the skill
33
+ @workspace-maxxing
34
+
35
+ # 3. Ask it to create something
36
+ "Create a workspace for lead scraping"
37
+ ```
38
+
39
+ The skill does everything else—creates folder structure, builds the agent, verifies tools, runs self-improvement.
40
+
41
+ ## What You Get
42
+
43
+ When you ask for a "lead scraping" workspace:
44
+
45
+ ```
46
+ lead-scraper/
47
+ ├── .agents/skills/lead-scraper/ ← Invokable with @lead-scraper
48
+ │ ├── SKILL.md
49
+ │ ├── prompts/
50
+ │ └── config.json
51
+ ├── 01-input/ ← Stage 1: Input
52
+ ├── 02-process/ ← Stage 2: Processing
53
+ ├── 03-output/ ← Stage 3: Output
54
+ ├── 00-meta/ ← Metadata & tools
55
+ ├── SYSTEM.md ← Global rules
56
+ └── CONTEXT.md ← Routing
57
+ ```
58
+
59
+ Now use `@lead-scraper` to run that workflow anytime.
60
+
61
+ ## Features
62
+
63
+ ### 🎯 Agent Creation
64
+ - Create invokable agents for any workflow
65
+ - Agents self-improve until score ≥ 85
66
+ - Built-in test case generation & validation
67
+
68
+ ### 🔧 Automatic Tool Discovery
69
+ - Checks what native tools your AI agent has
70
+ - Verifies tool accessibility with test runs
71
+ - Installs missing MCPs or CLI tools automatically
72
+
73
+ ### 📁 ICM Workspace Structure
74
+ - SYSTEM.md (global rules)
75
+ - CONTEXT.md (routing)
76
+ - Numbered stage folders (01-input, 02-process, 03-output)
77
+ - 00-meta for tools & execution logs
78
+
79
+ ### 🔄 Multi-Platform Support
80
+
81
+ | Platform | Installation |
82
+ |----------|--------------|
83
+ | OpenCode | `npx workspace-maxxing install` |
84
+ | Claude Code | `npx workspace-maxxing --claude` |
85
+ | GitHub Copilot | `npx workspace-maxxing --copilot` |
86
+ | Gemini CLI | `npx workspace-maxxing --gemini` |
87
+
88
+ ## Commands
89
+
90
+ ### CLI Commands
91
+
92
+ ```bash
93
+ # Install the skill
94
+ npx workspace-maxxing install
95
+
96
+ # Install for specific platform
97
+ npx workspace-maxxing --opencode
98
+
99
+ # Legacy commands (still work)
100
+ npx workspace-maxxing init
101
+ npx workspace-maxxing --create-workspace --workspace-name "My Project"
102
+ ```
103
+
104
+ ### In Your AI Agent
105
+
106
+ When you invoke `@workspace-maxxing`, you can ask:
107
+
108
+ | Request | Action |
109
+ |---------|--------|
110
+ | `"Build a workspace for X"` | Creates ICM workspace |
111
+ | `"Create an agent for Y"` | Creates invokable @agent |
112
+ | `"Validate my workspace"` | Checks ICM compliance |
113
+ | `"Improve my workspace"` | Runs autonomous iteration |
114
+ | `"Add tools for Z"` | Installs required tools |
115
+
116
+ ## Architecture
117
+
118
+ ```
119
+ ┌─────────────────────────────────────────────────────┐
120
+ │ @workspace-maxxing (invoked by user) │
121
+ ├─────────────────────────────────────────────────────┤
122
+ │ 1. RESEARCH → Analyze the request │
123
+ │ 2. TOOLING → Discover & install tools │
124
+ │ 3. ARCHITECTURE → Design workspace structure │
125
+ │ 4. BUILD → Create ICM folders & files │
126
+ │ 5. AGENT → Build invokable @agent │
127
+ │ 6. ITERATE → Self-improve until robust │
128
+ │ 7. DELIVER → Complete workspace + agent │
129
+ └─────────────────────────────────────────────────────┘
130
+ ```
131
+
132
+ ## What's Inside
133
+
134
+ | File/Folder | Purpose |
135
+ |-------------|---------|
136
+ | `SKILL.md` | Main skill definition |
137
+ | `skills/` | Sub-skills (research, architecture, tooling, etc.) |
138
+ | `scripts/` | Executable scripts (scaffold, validate, dispatch) |
139
+ | `.workspace-templates/` | ICM workspace templates |
140
+
141
+ ## The Iron Law
142
+
143
+ ```
144
+ NO BUILD WITHOUT PLAN
145
+ NO PLAN WITHOUT RESEARCH
146
+ NO TOOL DISCOVERY BEFORE AGENT DELIVERY
147
+ NO IMPROVEMENT WITHOUT VALIDATION
148
+ ```
149
+
150
+ ## Requirements
151
+
152
+ - Node.js 18+
153
+ - npm or yarn
154
+ - An AI agent (OpenCode, Claude, Copilot, or Gemini)
155
+
156
+ ## Contributing
157
+
158
+ Contributions welcome! Please read the [contributing guide](CONTRIBUTING.md) first.
159
+
160
+ ## License
161
+
162
+ MIT © [Eric Julian Deguzman](https://github.com/ericjdz)
163
+
164
+ ---
165
+
166
+ <p align="center">Made with 🚀 by the workspace-maxxing team</p>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "workspace-maxxing",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "description": "npx-installable skill for AI agents to create structured workspaces using ICM methodology",
5
5
  "bin": {
6
6
  "workspace-maxxing": "dist/index.js"