workspace-maxxing 0.1.0

package/docs/superpowers/specs/2026-04-08-workflow-prompt-hardening-design.md

@@ -0,0 +1,146 @@
+# Workflow Prompt Hardening for Scaffolded Workspaces — Design Spec
+
+## Overview
+
+Harden generated workspace prompts so agents reliably follow the intended workflow stages and loading discipline. This design upgrades scaffolded `SYSTEM.md`, root `CONTEXT.md`, and stage-level `CONTEXT.md` generation, aligns shipped template docs to the same structure, and introduces stricter validation checks that enforce both structure and workflow semantics.
+
+## Goals
+
+1. Make scaffold-generated prompts robust enough to guide stage-correct execution.
+2. Ensure prompt structures are consistent across generated workspaces and shipped templates.
+3. Enforce workflow contracts through `validate.ts` so prompt regressions fail early.
+4. Preserve existing script ergonomics (same CLI usage and pass/fail exit behavior).
+
+## Non-Goals
+
+1. No anti-rationalization or iron-law requirement in validation for this phase.
+2. No orchestrator or benchmark behavior changes.
+3. No package or dependency changes (Node builtins only).
+
+## Architecture
+
+### 1) Generation Contract (Scaffold)
+
+File: `src/scripts/scaffold.ts`
+
+#### SYSTEM.md (root) required sections
+- `## Role`
+- `## Folder Map`
+- `## Workflow Rules`
+- `## Stage Boundaries`
+- `## Tooling Policy`
+
+The generated content must explicitly communicate:
+- One-way stage dependencies.
+- Numbered stage progression.
+- Selective loading expectations.
+- Canonical-source behavior (avoid duplication).
+
+#### CONTEXT.md (root router) required sections
+- `## How to Use This File`
+- `## Task Routing`
+- `## Loading Order`
+- `## Stage Handoff Routing`
+- `## Escalation`
+
+The generated router must:
+- Route workspace intents to specific stage context files.
+- Include deterministic loading order (`SYSTEM.md` first, then root `CONTEXT.md`, then stage `CONTEXT.md`, then minimal task files).
+- Describe how to move from one stage to the next.
+
+#### Stage CONTEXT.md required sections
+- `## Purpose`
+- `## Inputs`
+- `## Outputs`
+- `## Dependencies`
+- `## Completion Criteria`
+- `## Handoff`
+
+Each stage context must include enough contract detail to prevent generic or cross-stage ambiguous behavior.
+
+### 2) Template Alignment
+
+Files:
+- `templates/.workspace-templates/SYSTEM.md`
+- `templates/.workspace-templates/CONTEXT.md`
+- `templates/.workspace-templates/workspace/01-input/CONTEXT.md`
+- `templates/.workspace-templates/workspace/02-process/CONTEXT.md`
+- `templates/.workspace-templates/workspace/03-output/CONTEXT.md`
+
+These files will be updated to match the same generation contract so both:
+- scaffolded workspaces, and
+- packaged templates
+
+provide consistent guidance quality.
+
+### 3) Validation Contract (Structural + Workflow Strictness)
+
+File: `src/scripts/validate.ts`
+
+#### Root checks
+- `SYSTEM.md` exists.
+- `SYSTEM.md` contains required section headings.
+- Root `CONTEXT.md` exists.
+- Root `CONTEXT.md` contains required section headings.
+
+#### Stage checks
+For each numbered stage folder:
+- `CONTEXT.md` exists and is non-empty.
+- Stage `CONTEXT.md` contains all required stage section headings.
+
+#### Workflow consistency checks
+- Every discovered numbered stage appears in root routing.
+- Routed stage targets resolve to existing stage `CONTEXT.md` files.
+- Root loading order enforces selective loading.
+- Dependency direction rule: a stage must not depend on a later-numbered stage.
+
+#### Output behavior
+- Keep check-by-check result structure and human-readable console reporting.
+- Keep exit semantics unchanged (`0` pass, `1` fail).
+
+## Data Flow
+
+1. `scaffold.ts` generates robust prompt contracts at root and stage levels.
+2. Agents load root documents, route into stage contexts, and follow stage boundaries.
+3. `validate.ts` enforces structural and workflow contracts.
+4. Iteration/orchestration logic consumes stronger workflow prompts and fails fast on doc drift.
+
+## Testing Strategy (TDD)
+
+### Scaffold tests (`tests/scaffold.test.ts`)
+Add failing tests first for:
+- SYSTEM required section headings.
+- Root CONTEXT required section headings.
+- Stage CONTEXT required section headings including Completion Criteria and Handoff.
+- Root routing references all generated numbered stages.
+
+### Validate tests (`tests/validate.test.ts`)
+Add failing tests first for:
+- Missing SYSTEM required sections.
+- Missing root CONTEXT required sections.
+- Missing stage required sections.
+- Missing stage routing coverage in root router.
+- Dependency direction violation (later-stage dependency).
+
+### Regression checks
+- Existing scaffold/validate expectations that remain valid should still pass.
+- Run targeted suites first, then full suite and build.
+
+## Risks and Mitigations
+
+1. Risk: False negatives from strict heading checks.
+- Mitigation: validate by section headings that are stable and intentionally generated.
+
+2. Risk: Overly rigid wording constraints.
+- Mitigation: enforce section presence and key workflow semantics, not full text equality.
+
+3. Risk: Breakage in existing test fixtures.
+- Mitigation: update fixture content only where new contract explicitly requires it.
+
+## Acceptance Criteria
+
+1. Scaffold-generated `SYSTEM.md`, root `CONTEXT.md`, and stage `CONTEXT.md` files contain all required sections.
+2. Shipped template docs use the same robust structure.
+3. `validate.ts` fails when required sections or workflow consistency rules are violated.
+4. Focused scaffold and validate test suites pass.
+5. Full repository test suite and TypeScript build pass.

package/docs/superpowers/specs/2026-04-12-workspace-agent-creation-design.md

@@ -0,0 +1,239 @@
+# Workspace-Maxxing with Invokable Agent Creation - Design Spec
+
+## Overview
+
+Extends `workspace-maxxing` skill to create, deliver, and iteratively improve an autonomous workflow agent inside the generated workspace. The skill builds both the ICM folder structure AND a self-improving agent that can be invoked with `@` in the workspace.
+
+## Goals
+
+1. Create invokable sub-agent inside the generated workspace
+2. Agent implements the actual workflow use case (not just the workspace structure)
+3. Self-improvement loop tests and strengthens the agent during build phase
+4. Backward compatible with existing workspace-maxxing behavior
+5. Multi-platform support (OpenCode, Claude Code, Copilot, Gemini)
+
+## Non-Goals
+
+1. Agent that persists outside the workspace (workspace-local only)
+2. Real-time self-improvement after delivery (improvement only during build)
+3. UI changes to workspace-maxxing skill
+
+## Architecture
+
+### Package Structure
+
+```
+workspace-maxxing/
+├── SKILL.md                    # Main skill entry
+├── package.json
+├── src/
+│   ├── index.ts                # Main entry, orchestration
+│   ├── scaffold.ts              # Creates ICM workspace
+│   ├── agent-creator.ts        # Creates @agent implementation
+│   ├── agent-iterator.ts       # Self-improvement loop
+│   └── installer.ts             # Platform-specific install
+├── scripts/
+│   ├── scaffold.ts              # (existing)
+│   ├── validate.ts             # (existing)
+│   ├── benchmark.ts            # (existing)
+│   ├── dispatch.ts             # (existing)
+│   └── orchestrator.ts         # (existing)
+└── templates/
+    ├── workspace/               # ICM workspace template
+    └── agent/                   # Agent template base
+```
+
+### Agent Structure (Created Inside Workspace)
+
+```
+workspace/
+├── .agents/
+│   └── skills/
+│       └── @<purpose>/         # The invokable agent
+│           ├── SKILL.md
+│           ├── prompts/
+│           │   ├── system.md
+│           │   └── tasks/
+│           ├── tools/
+│           │   └── index.ts
+│           ├── tests/
+│           │   └── cases.json
+│           └── config.json
+├── 01-input/
+├── 02-process/
+├── 03-output/
+├── SYSTEM.md
+└── CONTEXT.md
+```
+
+## Core Workflow
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ workspace-maxxing execution                                     │
+├─────────────────────────────────────────────────────────────────┤
+│ 1. Research phase (dispatch research sub-skill)               │
+│ 2. Architecture phase (dispatch architecture sub-skill)       │
+│ 3. Build workspace (scaffold.ts)                               │
+│ 4. Create agent (agent-creator.ts)                            │
+│    - Generate agent name from purpose                          │
+│    - Create agent structure from template                      │
+│    - Initialize prompts based on workflow                      │
+│ 5. Iterate agent (agent-iterator.ts) - SELF-IMPROVING         │
+│    a. Generate test cases (edge, empty, various)              │
+│    b. Run agent with each test case                           │
+│    c. Assess robustness (score + issues)                      │
+│    d. If score < threshold: improve agent                     │
+│    e. Repeat until score >= threshold OR max-retries         │
+│ 6. Validate workspace (validate.ts)                           │
+│ 7. Install agent to platform skill directory                   │
+│ 8. Deliver                                                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Agent Self-Improvement Loop
+
+### Input
+
+- Agent implementation (prompts, tools, config)
+- Test case generation rules (edge cases, empty states, varied inputs)
+
+### Process
+
+1. **Generate test cases** - Create diverse test inputs based on workflow type
+2. **Execute agent** - Run agent with each test case, capture outputs
+3. **Assess robustness** - Check for:
+   - Crashes or errors
+   - Invalid outputs
+   - Edge case handling
+   - Empty input handling
+4. **Score** - Compute robustness score (0-100)
+5. **Improve** - If score < threshold, modify prompts/tools to fix issues
+6. **Repeat** - Max 3 improvement cycles per batch
+
+### Output
+
+- Improved agent implementation
+- Test case results with pass/fail per case
+- Robustness score
+- Iteration log
+
+### Thresholds
+
+- Default robustness threshold: 85
+- Max iteration cycles: 3 per batch
+- Batch size: 3 test cases
+
+## Agent Naming
+
+- **Pattern**: `@<purpose>` derived from workspace purpose
+- **Generation**: Convert workspace name/purpose to lowercase, hyphenated
+- **Examples**:
+  - "Daily Digest" → `@daily-digest`
+  - "Project Tracker" → `@project-tracker`
+  - "AI News Aggregator" → `@ai-news-aggregator`
+
+## Platform Integration
+
+### OpenCode
+
+- Location: `workspace/.agents/skills/@<name>/`
+- Invocation: `@agent-name`
+- Auto-load on first mention
+
+### Claude Code
+
+- Location: `workspace/.claude/skills/<name>/`
+- Invocation: `{@name}` in prompts or instructions
+- Manual first invocation required
+
+### GitHub Copilot
+
+- Location: `workspace/.github/copilot-instructions/<name>.md`
+- Invocation: Through inline instructions
+
+### Gemini CLI
+
+- Location: `workspace/.gemini/skills/<name>/`
+- Invocation: Follows Gemini instruction format
+
+## Backward Compatibility
+
+- **Default behavior**: Creates workspace + agent (new behavior)
+- **Opt-out**: `--no-agent` flag creates workspace-only (existing behavior)
+- **Detection**: If no agent flag specified, assumes with-agent
+- **Existing scripts**: Unchanged, work as before
+- **Existing workspaces**: No migration needed
+
+## Configuration
+
+### Workspace-Maxxing Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--with-agent` | true | Create invokable agent |
+| `--agent-name` | auto | Custom agent name (overrides auto) |
+| `--robustness-threshold` | 85 | Min score to pass iteration |
+| `--max-agent-iterations` | 3 | Max improvement cycles |
+
+### Agent Config
+
+```json
+{
+  "name": "@daily-digest",
+  "purpose": "Create daily AI news digest",
+  "platforms": ["opencode", "claude", "copilot", "gemini"],
+  "robustnessThreshold": 85,
+  "iterationCount": 0,
+  "testCases": []
+}
+```
+
+## Anti-Patterns
+
+| Thought | Reality |
+|---------|---------|
+| "The agent works for basic cases" | Edge cases and empty states matter. Iterate until threshold. |
+| "One iteration is enough" | Self-improvement needs multiple cycles. |
+| "User will refine the agent later" | Goal is robust agent on delivery. |
+| "Agent validation is optional" | Robustness check is mandatory gate. |
+
+## Acceptance Criteria
+
+1. Workspace-maxxing creates both folder structure AND agent
+2. Agent is invokable with `@<name>` in supported platforms
+3. Self-improvement loop runs during build, achieves score >= 85
+4. Backward compatible - existing usage unchanged with `--no-agent`
+5. Agent persists in workspace, survives session restart
+6. Iteration logs stored in workspace for debugging
+7. Multi-platform installation works (OpenCode, Claude, Copilot, Gemini)
+
+## Risks and Mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| Agent name collision in workspace | Check existing agents, append number if needed |
+| Platform detection fails | Default to OpenCode, log warning |
+| Iteration infinite loop | Max 3 cycles, escalate after threshold not met |
+| Agent template incomplete | Provide minimal viable template, improve over time |
+
+## File Changes
+
+### New Files
+
+- `src/agent-creator.ts` - Creates agent implementation
+- `src/agent-iterator.ts` - Self-improvement loop
+- `templates/agent/` - Agent template base
+
+### Modified Files
+
+- `SKILL.md` - Update workflow to include agent creation
+- `src/index.ts` - Add agent orchestration
+- `package.json` - Add dependencies if needed
+
+## Timeline
+
+1. Phase 1: Agent creator (scaffold agent structure from template)
+2. Phase 2: Agent iterator (self-improvement loop)
+3. Phase 3: Platform installer (multi-platform support)
+4. Phase 4: Backward compatibility (--no-agent flag)

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "workspace-maxxing",
+  "version": "0.1.0",
+  "description": "npx-installable skill for AI agents to create structured workspaces using ICM methodology",
+  "bin": {
+    "workspace-maxxing": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "test": "jest --config jest.config.js",
+    "test:watch": "jest --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["ai-agent", "workspace", "skill", "opencode", "icm"],
+  "author": "Eric Julian Deguzman <ericjuliandeguzman77@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ericjdz/workflow-maxxing"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.12",
+    "@types/node": "^20.11.0",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.1.2",
+    "typescript": "^5.3.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/agent-creator.ts

@@ -0,0 +1,180 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface AgentOptions {
+  name: string;
+  purpose: string;
+  workspacePath: string;
+  platforms?: string[];
+}
+
+export function generateAgentName(purpose: string): string {
+  // Convert "Daily Digest" -> "@daily-digest"
+  // Convert "AI News Aggregator" -> "@ai-news-aggregator"
+  const cleaned = purpose
+    .toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .trim();
+  return `@${cleaned}`;
+}
+
+export function createAgent(options: AgentOptions): void {
+  const { name, purpose, workspacePath } = options;
+  
+  // Remove @ prefix for directory name
+  const dirName = name.startsWith('@') ? name.slice(1) : name;
+  const agentDir = path.join(workspacePath, '.agents', 'skills', dirName);
+  
+  // Create directory structure
+  fs.mkdirSync(path.join(agentDir, 'prompts', 'tasks'), { recursive: true });
+  fs.mkdirSync(path.join(agentDir, 'tools'), { recursive: true });
+  fs.mkdirSync(path.join(agentDir, 'tests'), { recursive: true });
+  
+  // Write SKILL.md
+  const skillContent = generateSkillMd(name, purpose);
+  fs.writeFileSync(path.join(agentDir, 'SKILL.md'), skillContent);
+  
+  // Write config.json
+  const configContent = JSON.stringify({
+    name,
+    purpose,
+    platforms: options.platforms ?? ['opencode', 'claude', 'copilot', 'gemini'],
+    robustnessThreshold: 85,
+    iterationCount: 0,
+    testCases: [],
+  }, null, 2);
+  fs.writeFileSync(path.join(agentDir, 'config.json'), configContent);
+  
+  // Write prompts/system.md
+  const systemPrompt = generateSystemPrompt(name, purpose);
+  fs.writeFileSync(path.join(agentDir, 'prompts', 'system.md'), systemPrompt);
+  
+  // Write prompts/tasks/ default task prompt
+  const taskPrompt = generateTaskPrompt(name, purpose);
+  fs.writeFileSync(path.join(agentDir, 'prompts', 'tasks', 'default.md'), taskPrompt);
+  
+  console.log(`Agent "${name}" created at: ${agentDir}`);
+}
+
+function generateSkillMd(name: string, purpose: string): string {
+  const dirName = name.startsWith('@') ? name.slice(1) : name;
+  return `---
+name: ${name}
+description: "${purpose}. Use when user wants to run this workflow."
+triggers: ["${name}", "${purpose.toLowerCase()}", "run ${dirName} workflow"]
+---
+
+# ${name} Agent
+
+## Purpose
+${purpose}
+
+## When to Use
+- User wants to execute the workflow
+- User asks to process inputs and generate outputs
+- User wants to run automated tasks
+
+## The Iron Law
+
+NO SKIPPING WORKFLOW STEPS
+NO IMPLEMENTATION BEFORE PLAN
+NO CLAIMING DONE WITHOUT OUTPUT
+
+## Capabilities
+- Execute workflow tasks following ICM stage boundaries
+- Process inputs from 01-input/ and generate outputs in 03-output/
+- Read workspace context (SYSTEM.md, stage CONTEXT.md)
+- Produce structured markdown outputs
+
+## How It Works
+
+1. **Read Context** - Load SYSTEM.md, root CONTEXT.md, and relevant stage CONTEXT.md
+2. **Process Task** - Execute the requested workflow step
+3. **Write Output** - Save results to appropriate stage folder
+4. **Report** - Provide summary in chat + log to file
+
+## Output Format
+
+- Stage outputs as markdown files in numbered folders
+- Progress reported in hybrid format (chat summary + file details)
+- Results logged for traceability
+
+## Configuration
+See config.json for agent configuration options.
+
+## Anti-Rationalization
+
+| Thought | Reality |
+|---------|----------|
+| "I know what to do" | Read the stage CONTEXT.md first |
+| "Good enough" | Follow the workflow exactly |
+| "Skip a stage" | Workflow stages exist for a reason |
+| "No output needed" | Every task produces artifacts |
+`;
+}
+
+function generateSystemPrompt(name: string, purpose: string): string {
+  const dirName = name.startsWith('@') ? name.slice(1) : name;
+  return `# ${name} - System Prompt
+
+## Role
+You are ${name}, an autonomous workflow agent that executes the ${purpose} workflow.
+
+## Workspace Context
+- Read \`SYSTEM.md\` first for global rules
+- Load root \`CONTEXT.md\` for routing
+- Read relevant stage \`CONTEXT.md\` for specific instructions
+
+## Workflow Execution
+
+1. **Understand the request** - What does the user want to accomplish?
+2. **Load appropriate context** - Read only the needed stage files
+3. **Execute the task** - Follow the stage-specific instructions
+4. **Produce output** - Write results to the appropriate folder
+5. **Report progress** - Provide summary in chat + log to file
+
+## Stage Boundaries
+- \`01-input/\` - Input collection and validation
+- \`02-process/\` - Processing and transformation
+- \`03-output/\` - Output generation and delivery
+- \`00-meta/\` - Configuration and tools
+
+## Constraints
+- Stay within workspace scope
+- Follow ICM folder boundaries strictly
+- Do not create product implementation code
+- Keep outputs as markdown artifacts
+- Report progress in hybrid format (chat + files)
+
+## Error Handling
+- If context is missing, ask for clarification
+- If stage dependencies are unclear, check execution-log.md
+- If task is outside workspace scope, redirect to workflow design
+`;
+}
+
+function generateTaskPrompt(name: string, purpose: string): string {
+  return `# Default Task Prompt
+
+## Task
+Execute the workflow request from the user.
+
+## Input
+Read the user's request and determine which workflow stage applies.
+
+## Process
+1. Load the relevant stage context
+2. Follow the stage's completion criteria
+3. Produce the required outputs
+
+## Output
+Write results to the appropriate stage folder as markdown artifacts.
+
+## Success Criteria
+- Output conforms to stage purpose
+- Required evidence is produced
+- Handoff notes updated for next stage
+`;
+}