workspace-maxxing 0.3.0 → 0.5.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
  1. package/README.md +54 -66
  2. package/package.json +1 -1
  3. package/templates/SKILL.md +78 -19
package/README.md CHANGED
@@ -1,93 +1,81 @@
1
1
  # workspace-maxxing
2
2
 
3
- An installable skill package for AI coding agents that scaffolds, validates, and iterates on ICM-style workspaces with explicit workflow routing. Now with **invokable agent creation** - the skill can create autonomous agents that can be invoked with `@` in your workspace.
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
4
 
5
- ## Why This Exists
5
+ ## The Flow
6
6
 
7
- Most agent workspaces drift over time because prompts are underspecified and context loading is inconsistent. `workspace-maxxing` provides a repeatable workflow that generates structured `SYSTEM.md` and `CONTEXT.md` contracts, validates them, and improves them through autonomous iteration.
8
-
9
- ## Features
10
-
11
- - Multi-agent install targets: OpenCode, Claude Code, GitHub Copilot, Gemini CLI
12
- - ICM workspace scaffolding with robust root and per-stage context contracts
13
- - Workflow-aware validation (routing coverage, stage dependency direction, selective loading)
14
- - Batched autonomous iteration via orchestrator + worker/fixer loops
15
- - Built-in test-case generation and weighted benchmarking
16
- - **Create invokable agents** - the skill can build autonomous agents that can be invoked with `@` in your workspace
17
- - **Self-improving agents** - created agents run through iteration loops to ensure robustness
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
+ ```
18
13
 
19
14
  ## Quick Start
20
15
 
21
- ### One Command Does Everything
22
-
23
16
  ```bash
24
- # Create workspace with agent (recommended)
25
- npx workspace-maxxing init
26
-
27
- # Install skill to OpenCode
17
+ # Step 1: Install the skill to your project
28
18
  npx workspace-maxxing install
29
19
 
30
- # Or use the old way (still works)
31
- npx workspace-maxxing --opencode
32
- ```
33
-
34
- That's it! No extra flags needed.
35
-
36
- ## Two Main Use Cases
20
+ # Step 2: In your AI agent, invoke the skill
21
+ @workspace-maxxing
37
22
 
38
- ### Use Case 1: Create a New Workspace with Agent
39
-
40
- When you want to start a new workflow project:
41
-
42
- ```bash
43
- # Basic (creates "My Workspace" with 3 stages)
44
- npx workspace-maxxing init
23
+ # Step 3: Ask it to create something
24
+ "Create a workspace for my daily news aggregator"
25
+ ```
45
26
 
46
- # Custom name
47
- npx workspace-maxxing init --workspace-name "Daily Digest"
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
48
34
 
49
- # Custom stages
50
- npx workspace-maxxing init --stages "01-input,02-process,03-output,04-deploy"
35
+ ## What Gets Created
51
36
 
52
- # Without agent (backward compatible)
53
- npx workspace-maxxing init --no-agent
37
+ When you ask `@workspace-maxxing` to create a workspace for "Daily Digest":
54
38
 
55
- # To specific folder
56
- npx workspace-maxxing init --output "./my-workspace"
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
57
49
  ```
58
50
 
59
- This creates:
60
- - ICM workspace folder structure
61
- - Invokable `@agent` in `.agents/skills/`
62
- - Runs self-improvement loop (score >= 85)
51
+ Now you can use `@daily-digest` to run that workflow!
63
52
 
64
- ### Use Case 2: Install the Skill to Your Project
53
+ ## Tool Discovery (Automatic)
65
54
 
66
- When you want to use workspace-maxxing as a skill in your AI agent:
55
+ When you ask `@workspace-maxxing` to create an agent (e.g., "lead scraper"), it **automatically**:
67
56
 
68
- ```bash
69
- # Install to current project (OpenCode)
70
- npx workspace-maxxing install
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
71
61
 
72
- # Install to specific platform
73
- npx workspace-maxxing --opencode
74
- npx workspace-maxxing --claude
75
- npx workspace-maxxing --copilot
76
- npx workspace-maxxing --gemini
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
77
70
  ```
78
71
 
79
- This installs the skill to `.agents/skills/workspace-maxxing/` so you can invoke it in your AI agent session with `@workspace-maxxing`.
80
-
81
- ## CLI Options
72
+ ## Commands
82
73
 
83
- | Option | Description |
84
- |--------|-------------|
85
- | `init` | Create workspace with agent (default command) |
86
- | `install` | Install skill to current project |
87
- | `--workspace-name` | Name of the workspace |
88
- | `--stages` | Comma-separated stages |
89
- | `--output` | Output directory |
90
- | `--no-agent` | Create workspace without agent |
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 |
91
79
  | `--stages` | "01-input,02-process,03-output" | Comma-separated stage names |
92
80
  | `--output` | "./workspace" | Output directory |
93
81
  | `--agent-name` | auto-generated (@workspace-name) | Custom agent name |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "workspace-maxxing",
3
- "version": "0.3.0",
3
+ "version": "0.5.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"
package/templates/SKILL.md CHANGED
@@ -1,13 +1,19 @@
1
1
  ---
2
2
  name: workspace-maxxing
3
- description: "Autonomously creates, validates, and improves ICM-compliant workspaces using batched parallel sub-agents. Use when user asks to 'build a workspace', 'create a workflow', 'automate a process', 'improve this workspace', 'validate this workspace', 'iterate on this workspace', or 'run test cases'."
3
+ description: "Autonomously creates, validates, and improves ICM-compliant workspaces using batched parallel sub-agents. Use when user asks to 'build a workspace', 'create a workflow', 'automate a process', 'improve this workspace', 'validate this workspace', 'iterate on this workspace', 'run test cases', or 'create an agent'."
4
4
  ---
5
5
 
6
6
  # Workspace-Maxxing Skill
7
7
 
8
8
  ## Overview
9
9
 
10
- Autonomous workflow system that creates, validates, and improves ICM-compliant workspaces through phased execution, batched parallel sub-agent iteration, and condition-driven improvement loops.
10
+ This is an **AI agent skill** that creates ICM-compliant workspaces with invokable agents.
11
+
12
+ **User Flow:**
13
+ 1. Install: `npx workspace-maxxing install`
14
+ 2. Invoke: `@workspace-maxxing` in your AI agent
15
+ 3. Request: "Create a daily digest workspace" (or similar)
16
+ 4. The skill builds: ICM workspace + invokable agent
11
17
 
12
18
  ## When to Use
13
19
 
@@ -18,6 +24,47 @@ Autonomous workflow system that creates, validates, and improves ICM-compliant w
18
24
  - User asks to run test cases against a workspace
19
25
  - **User asks to create an agent for a specific task** (e.g., "create a daily digest agent", "make a news aggregator agent")
20
26
 
27
+ ## User Commands (to the AI agent)
28
+
29
+ When you invoke `@workspace-maxxing`, you can ask:
30
+
31
+ | Request | What Happens |
32
+ |---------|-------------|
33
+ | "Build a workspace for X" | Creates ICM workspace with X workflow |
34
+ | "Create an agent for Y" | Creates invokable @agent for Y task |
35
+ | "Validate my workspace" | Checks ICM compliance |
36
+ | "Improve my workspace" | Runs autonomous iteration |
37
+ | "Add tools for Z" | Uses tooling sub-skill to install tools |
38
+
39
+ **IMPORTANT - Tool Discovery Before Agent Delivery:**
40
+
41
+ When creating ANY agent, ALWAYS do this FIRST:
42
+
43
+ 1. **Check native tools** - What capabilities does the AI agent already have?
44
+ - Playwright, puppeteer for browser automation?
45
+ - Curl, wget for HTTP requests?
46
+ - File system access?
47
+ - Database connections?
48
+
49
+ 2. **Verify tool accessibility** - Run a simple test to confirm tools work:
50
+ ```
51
+ Test: Can you make a simple HTTP request?
52
+ Test: Can you list files in the current directory?
53
+ Test: Can you execute a simple script?
54
+ ```
55
+
56
+ 3. **Install missing tools** - If native tools are insufficient:
57
+ - Use `/skill tooling` to install MCP servers
58
+ - Use `npm install` for CLI tools
59
+ - Document installed tools in `00-meta/tools.md`
60
+
61
+ 4. **Include tool instructions in agent prompts** - The created agent must know:
62
+ - What tools are available
63
+ - How to use them
64
+ - Any rate limits or constraints
65
+
66
+ The skill will then execute the appropriate phases internally.
67
+
21
68
  ## Tool Discovery & Agent Harness
22
69
 
23
70
  This skill is designed to **fully utilize its agent harness**. When running:
@@ -86,40 +133,51 @@ This skill provides a complete agent development harness:
86
133
 
87
134
  ## Agent Creation Workflow
88
135
 
89
- When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a daily digest agent"), follow this flow:
136
+ When you invoke `workspace-maxxing` with a request to create an agent (e.g., "create a lead scraping agent"), follow this flow:
90
137
 
91
138
  ```
92
- 1. Parse the request to extract the agent purpose (e.g., "Daily Digest")
93
- 2. Create ICM workspace structure (SYSTEM.md, CONTEXT.md, stage folders)
94
- 3. Create invokable agent in .agents/skills/@<purpose>/
95
- 4. Run self-improvement loop on the agent
139
+ 1. Parse the request to extract the agent purpose (e.g., "Lead Scraper")
140
+ 2. DISCOVER TOOLS:
141
+ - Check what native tools are available in the AI agent (playwright, puppeteer, curl, etc.)
142
+ - Verify tool accessibility by running a simple test
143
+ - If native tools are insufficient, use tooling sub-skill to install MCPs or CLI tools
144
+ - Document tools in 00-meta/tools.md
145
+ 3. Create ICM workspace structure (SYSTEM.md, CONTEXT.md, stage folders)
146
+ 4. Create invokable agent in .agents/skills/@<purpose>/
147
+ - Include tool usage instructions in the agent prompts
148
+ 5. Run self-improvement loop on the agent
96
149
  - Generate test cases (edge, empty, varied inputs)
97
150
  - Validate agent handling
98
151
  - Score robustness (0-100)
99
152
  - If score < 85: improve prompts, retry
100
153
  - Repeat until score >= 85 or max iterations (3)
101
- 5. Install agent for platform (OpenCode/Claude/Copilot/Gemini)
102
- 6. Deliver workspace with robust agent
154
+ 6. Install agent for platform (OpenCode/Claude/Copilot/Gemini)
155
+ 7. Deliver workspace with robust agent
103
156
  ```
104
157
 
105
- ### Agent Creation Example
158
+ ### Agent Creation with Tool Discovery Example
106
159
 
107
- User: "Create a daily digest agent"
160
+ User: "Create an agent that scrapes internet data for leads"
108
161
 
109
162
  ```
110
- -> Extract purpose: "Daily Digest"
111
- -> DISCOVER TOOLS: Use /skill tooling to find relevant tools (e.g., RSS, web scraping, summarization)
163
+ -> Extract purpose: "Lead Scraper"
164
+ -> DISCOVER TOOLS:
165
+ - Check: Does agent have playwright? → Yes, test it works
166
+ - Check: Does agent have curl/wget? → Yes, verify accessible
167
+ - Check: Any MCP servers for scraping? → No, need to install
168
+ - Action: Run tooling sub-skill to install puppeteer or similar
169
+ - Verify: Test the tool with a simple request
112
170
  -> Create workspace with stages: 01-input, 02-process, 03-output
113
- -> Create agent: @daily-digest in .agents/skills/daily-digest/
171
+ -> Create agent: @lead-scraper with tool instructions in prompts
114
172
  -> Run iteration:
115
- - Test: empty input -> fix prompts
116
- - Test: special chars -> fix prompts
117
- - Test: normal input -> validate
173
+ - Test: scraping a page -> works
174
+ - Test: handling empty pages -> handles gracefully
175
+ - Test: rate limiting -> respects limits
118
176
  - Score >= 85? Yes -> deliver
119
- -> Agent is ready to invoke with @daily-digest
177
+ -> Agent is ready to invoke with @lead-scraper
120
178
  ```
121
179
 
122
- **Key**: Always look for and leverage tools when creating agents or workspaces.
180
+ **Tool Discovery is MANDATORY** - always check available tools, verify accessibility, and install missing tools before delivering the agent.
123
181
 
124
182
  ## When Not to Use
125
183
 
@@ -131,6 +189,7 @@ User: "Create a daily digest agent"
131
189
 
132
190
  NO BUILD WITHOUT PLAN
133
191
  NO PLAN WITHOUT RESEARCH
192
+ NO TOOL DISCOVERY BEFORE AGENT DELIVERY
134
193
  NO IMPROVEMENT WITHOUT VALIDATION
135
194
  NO COMPLETION CLAIM WITHOUT VERIFICATION
136
195
  NO PRODUCT IMPLEMENTATION INSIDE WORKSPACE BUILDING MODE