workspace-maxxing 0.1.0 → 0.3.0

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

@@ -1,146 +0,0 @@
-# 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

@@ -1,239 +0,0 @@
-# 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/workspace/00-meta/CONTEXT.md

@@ -1,3 +0,0 @@
-# 00-meta Context
-
-Metadata and tool inventory for the NoAgent Test workspace.

package/workspace/00-meta/execution-log.md

@@ -1,17 +0,0 @@
-# Execution Log
-
-## Stage Checklist
-
-- [ ] 01-input
-
-## Rules
-
-1. Mark a stage complete only after its completion criteria are satisfied.
-2. Stages must be checked in ascending numerical order.
-3. Every checked stage must have corresponding evidence notes.
-
-## Evidence Notes
-
-### 01-input
-- Artifacts:
-- Handoff Summary:

package/workspace/00-meta/tools.md

@@ -1,11 +0,0 @@
-## Tool Inventory
-
-## Installed Tools
-
-| Tool | Version | Manager | Installed |
-|------|---------|---------|-----------|
-| — | — | — | — |
-
-## Pending Tools
-
-List tools that are proposed but not yet approved.

package/workspace/01-input/CONTEXT.md

@@ -1,27 +0,0 @@
-# 01-input — Context
-
-## Purpose
-This folder executes the 01-input stage of the NoAgent Test workflow.
-
-## Inputs
-- Required data artifacts for 01-input
-- Upstream context from previous stage when applicable
-
-## Outputs
-- Stage-specific deliverables for downstream consumption
-- Updated markdown artifacts needed by the next stage
-
-## Dependencies
-- None (entry stage)
-
-## Required Evidence
-- Update `00-meta/execution-log.md` to mark 01-input complete before handoff.
-- Link or reference the markdown artifacts produced in this stage.
-
-## Completion Criteria
-- Required outputs are produced and non-empty
-- Outputs conform to stage purpose and markdown-first workflow format
-- Handoff notes are updated for downstream stage
-
-## Handoff
-- This is the terminal stage. Package and deliver final output.

package/workspace/CONTEXT.md

@@ -1,35 +0,0 @@
-# NoAgent Test — Context Router
-
-## How to Use This File
-Use this file to route each task to the smallest required context scope.
-
-## Task Routing
-This routing table maps task intent to the correct stage context.
-
-| When you need to... | Load | Why |
-|---------------------|------|-----|
-| Understand workspace constraints | `SYSTEM.md` | Global rules and stage boundaries |
-| Work in 01-input tasks | `01-input/CONTEXT.md` | Stage contract and required outputs |
-| Check available tools | `00-meta/tools.md` | Tool inventory and approval status |
-
-## Loading Order
-1. `SYSTEM.md` (always)
-2. This root `CONTEXT.md`
-3. One relevant stage `CONTEXT.md`
-4. Only the task files needed for that stage
-
-## Scope Guardrails
-- Route domain requests into workflow design steps and markdown deliverables.
-- Do not scaffold backend, frontend, or runtime product source files from this router.
-- Keep outputs file-structured and markdown-first across numbered workflow folders.
-
-## Sequential Routing Contract
-- Route only to the earliest incomplete stage in `00-meta/execution-log.md`.
-- Refuse jumps to later stages when earlier stages are not marked complete.
-- Append handoff notes for each completed stage before routing onward.
-
-## Stage Handoff Routing
-- `01-input` -> deliver final output and close loop
-
-## Escalation
-Escalate when required sections are missing, dependencies are contradictory, or no valid stage route can satisfy the task.

package/workspace/README.md

@@ -1,14 +0,0 @@
-# NoAgent Test Workspace
-
-## Structure
-
-- `01-input/`
-- `00-meta/`
-
-## Usage
-
-1. Follow the workflow stages in order
-2. Load CONTEXT.md files selectively — only what you need
-3. Update 00-meta/execution-log.md after each completed stage
-4. Keep outputs in stage folders as markdown workflow artifacts
-5. Run validate.ts to check ICM compliance

package/workspace/SYSTEM.md

@@ -1,36 +0,0 @@
-# NoAgent Test — System Prompt
-
-## Role
-You are an AI assistant operating inside the NoAgent Test workspace. Follow stage boundaries and route tasks through stage-specific CONTEXT files.
-
-## Folder Map
-
-| Stage | Folder | Purpose |
-|------:|--------|---------|
-| 1 | `01-input/` | Input collection and validation |
-| meta | `00-meta/` | Workspace configuration, tool inventory, and session notes |
-
-## Workflow Rules
-1. Read `SYSTEM.md` first, then root `CONTEXT.md`.
-2. Load only one stage `CONTEXT.md` at a time unless handoff explicitly requires another stage.
-3. Keep information canonical; do not duplicate facts across files.
-4. Maintain one-way stage dependencies from earlier stage numbers to later stage numbers.
-
-## Scope Guardrails
-- Build and maintain workflow documentation, not product implementation code.
-- Keep stage outputs as markdown artifacts (plans, checklists, prompts, routing notes).
-- If asked to build the product itself, capture that request as workflow requirements and stay in ICM workspace scope.
-
-## Sequential Execution Protocol
-1. Complete stages strictly in ascending numeric order.
-2. Record stage completion in `00-meta/execution-log.md` before moving to the next stage.
-3. Do not produce final deliverables until all prior stage checkboxes are complete.
-
-## Stage Boundaries
-- Each numbered folder is an execution stage.
-- A stage may consume upstream outputs but must not redefine upstream facts.
-- Cross-stage jumps require explicit routing through root `CONTEXT.md`.
-
-## Tooling Policy
-- Check `00-meta/tools.md` before proposing tool installation.
-- Document approved tooling changes in `00-meta/tools.md`.