workspace-management

Workspace Management

Unified skill covering issue decomposition, workspace structure and conventions, tracker metadata management, and eval infrastructure.

References

@skills/workspace-management/references/decomposition-guide.md @skills/workspace-management/references/type-catalog.md @skills/workspace-management/references/hierarchy-model.md @skills/workspace-management/references/workspace-structure.md @skills/workspace-management/references/tracker-integration.md

Contents

workspace-management/
├── references/
│   ├── decomposition-guide.md    # Core methodology for analyzing, sizing, splitting problems
│   ├── type-catalog.md           # All 19 issue types with descriptions and title formats
│   ├── hierarchy-model.md        # Epic -> Story -> Sub-issue hierarchy and sizing rules
│   ├── workspace-structure.md    # Workspace layout, entity types, wikilinks, frontmatter rules
│   └── tracker-integration.md    # External tracker integration (Linear, GitHub, Jira, etc.)
└── evals/
    ├── agents/
    │   └── meta-eval-expert.md
    ├── docs/
    │   └── dart-architecture.md
    ├── templates/
    │   ├── eval-template.md           # Documentation structure (shared)
    │   ├── eval-config-template.json  # Config format (shared)
    │   ├── eval-task-template.md      # Task format (shared)
    │   ├── python/
    │   │   ├── eval-script-template.py
    │   │   ├── test-eval-template.py
    │   │   ├── pre-push-hook.sh
    │   │   └── validation/
    │   │       └── all-tests-pass/
    │   ├── dart/
    │   │   ├── eval-script-template.dart
    │   │   ├── test-eval-template.dart
    │   │   ├── pre-push-hook.sh
    │   │   └── validation/
    │   │       └── all-tests-pass/
    │   └── typescript/
    │       ├── eval-script-template.ts
    │       ├── test-eval-template.ts
    │       ├── pre-push-hook.sh
    │       └── validation/
    │           └── all-tests-pass/
    └── tools/scripts/
        ├── python/
        │   ├── eval_base.py
        │   ├── eval_config_schema.json
        │   ├── run-evals.py
        │   └── run-eval.py
        ├── dart/
        │   ├── eval_base.dart
        │   └── run_evals.dart
        └── typescript/
            ├── eval_base.ts
            ├── run-evals.ts
            ├── run-eval.ts
            └── package.json

Resources

Issue Decomposition References

Path	What	When to Use
references/decomposition-guide.md	Core methodology for analyzing, sizing, and splitting problems	Any decomposition or issue creation
references/type-catalog.md	All 19 issue types with descriptions, when-to-use, and title formats	Picking the right type for each piece of work
references/hierarchy-model.md	Epic -> Story -> Sub-issue hierarchy rules and sizing constraints	Work involving multiple levels or parent-child structuring

Workspace Context References

Path	What	When to Use
references/workspace-structure.md	Workspace layout, entity types, wikilinks, frontmatter conventions	Setting up a workspace, creating any workspace entity, understanding the structure
references/tracker-integration.md	External tracker integration pattern and metadata structure	Connecting workspace issues to Linear, GitHub, Jira, or any tracker

Eval Shared Templates

Template	What	When to Use
evals/templates/eval-template.md	Eval documentation structure	Documenting any eval
evals/templates/eval-config-template.json	JSON config format	Creating eval.json
evals/templates/eval-task-template.md	Task format for failures	Understanding task output

Eval Python Resources

Resource	What	When to Use
evals/templates/python/eval-script-template.py	Eval script boilerplate	Creating Python evals
evals/templates/python/test-eval-template.py	pytest test template	Creating Python eval tests
evals/templates/python/pre-push-hook.sh	Git pre-push hook	Push protection
evals/templates/python/validation/all-tests-pass/	Validation eval	Installed by default
evals/tools/scripts/python/eval_base.py	BaseEval class	Copy to workspace/evals/
evals/tools/scripts/python/eval_config_schema.json	Eval config JSON schema	Config validation
evals/tools/scripts/python/run-evals.py	Eval runner	Copy to workspace/evals/
evals/tools/scripts/python/run-eval.py	Single eval runner	Copy to workspace/evals/

Eval Dart Resources

Resource	What	When to Use
evals/templates/dart/eval-script-template.dart	Eval script boilerplate	Creating Dart evals
evals/templates/dart/test-eval-template.dart	Dart test template	Creating Dart eval tests
evals/templates/dart/pre-push-hook.sh	Git pre-push hook	Push protection
evals/templates/dart/validation/all-tests-pass/	Validation eval	Installed by default
evals/tools/scripts/dart/eval_base.dart	BaseEval class	Copy to workspace/evals/
evals/tools/scripts/dart/run_evals.dart	Eval runner	Copy to workspace/evals/

Eval TypeScript Resources

Resource	What	When to Use
evals/templates/typescript/eval-script-template.ts	Eval script boilerplate	Creating TypeScript evals
evals/templates/typescript/test-eval-template.ts	Vitest test template	Creating TypeScript eval tests
evals/templates/typescript/pre-push-hook.sh	Git pre-push hook	Push protection
evals/templates/typescript/validation/all-tests-pass/	Validation eval	Installed by default
evals/tools/scripts/typescript/eval_base.ts	BaseEval class	Copy to workspace/evals/
evals/tools/scripts/typescript/run-evals.ts	Eval runner	Copy to workspace/evals/
evals/tools/scripts/typescript/run-eval.ts	Single eval runner	Copy to workspace/evals/
evals/tools/scripts/typescript/package.json	Package config (tsx + vitest)	Copy to workspace/evals/

Eval Agents

Agent	What	When to Use
evals/agents/meta-eval-expert.md	Meta eval expert agent	Eval design and review

Eval Docs

Doc	What	When to Use
evals/docs/dart-architecture.md	Dart eval architecture guide	Understanding Dart eval structure

Issue Type Templates

Located in templates/ at the plugin root. Used when creating issues:

Template	Type	When to Use
epic-template.md	🏔️ Epic	Large umbrella of work spanning multiple stories
feature-template.md	✨ Feature	Product capability spec with requirements and journeys
story-template.md	📘 Story	User-focused slice with journey and scenarios
bug-template.md	🐞 Bug	Something broken with reproduction steps
enhancement-template.md	🌱 Enhancement	Improving existing functionality
refactor-template.md	🧱 Refactor	Restructuring without behavior change
chore-template.md	🧹 Chore	Maintenance and housekeeping
design-template.md	🎨 Design	Design deliverables
development-template.md	🔧 Development	Full implementation plan across layers
business-logic-template.md	⚙️ Business Logic	Services, APIs, DTOs — no screens
ui-template.md	🖼️ UI	Components, views, design tokens — no business logic
research-template.md	🔬 Research	Time-boxed investigation
discovery-template.md	💡 Discovery	Early-stage idea exploration
test-template.md	🧪 Test	Automated test planning
qa-template.md	🔍 QA	Structured quality review
acceptance-template.md	✅ Acceptance	Step-by-step pass/fail verification
release-template.md	🚀 Release	Shipping a version
content-template.md	📣 Content	Creating and posting content
devops-template.md	🏗️ DevOps	Infrastructure and CI/CD changes

Commands

Command	What	When to Use
/create-ws-issues	Decompose problems into structured issue files	Breaking down work into agent-sized issues
/audit-ws-issues	Audit issue files with specialized agents	Validating issue quality before implementation
/develop-ws-issues	Orchestrate iterative chunk-based implementation	Implementing issues with review cycles
/review-ws-issues	Review implemented code against issue specs	Post-implementation quality verification
/fix-ws-issues	Fix feedback markers in issue files	Addressing review feedback on issues
/init-ws-evals	Initialize eval infrastructure (auto-detects language)	Setting up evals in a project
/create-ws-evals	Create a new eval	Adding a new eval
/run-ws-evals	Run all evals and report results	Validating project conventions
/suggest-ws-evals	Analyze codebase and suggest new evals	Discovering useful evals
/process-ws-evals	Fix violations from failed evals	Addressing eval failures
/fix-ws-evals	Fix feedback markers in eval files	Addressing review feedback on evals

Agents

Pre-implementation (Auditors)

Agent	Focus
ws-issue-architecture-auditor	Architectural gaps, contradictions, convention violations
ws-issue-project-auditor	Project structure violations, misplaced logic, naming breaches
ws-issue-nfr-auditor	Security, performance, maintainability, technical debt risks
ws-issue-test-auditor	Missing test scenarios, mock misuse, coverage gaps
ws-issue-uiux-auditor	Missing interaction states, accessibility, design system divergence

Post-implementation (Reviewers)

Agent	Focus
ws-issue-architecture-reviewer	Architectural faithfulness to issue specs
ws-issue-project-reviewer	Structural correctness against issue specs
ws-issue-nfr-reviewer	NFR compliance in implemented code
ws-issue-test-reviewer	Test quality and coverage faithfulness
ws-issue-uiux-reviewer	UI/UX faithfulness and quality

Tracker Metadata

Purpose

Store and maintain teams, labels, workflow statuses, and projects from the project's external tracker as a workspace reference. This data is used by commands like /create-ws-issues to populate issue metadata (labels, team assignments, project links).

Setup

1. Create a tracker metadata reference at workspace/context/references/{subject}/tracker-meta-data.md
2. Populate it with data exported from the tracker
3. Manually re-export and update the reference when tracker data changes

Metadata Structure

Workspace/Organization

• Name and tool identifier (Linear, GitHub, Jira, etc.)

Teams

Field	Description
Name	Team display name
Key	Short identifier (e.g., ENG, DES)
ID	Tracker-specific unique ID

Workflow Statuses

All statuses in the tracker's workflow pipeline, in order. Common statuses: Backlog, In Progress, In Review, Done, Canceled

Labels

Organized by category:

Category	Purpose	Examples
Type	Issue type classification	epic, feature, bug, chore
Team	Responsible team	mobile, backend, data
Priority	Urgency level	critical, high, medium, low
Effort	Work estimate	maximum, high, average, low
Value	Business value	maximum, high, average, low

Projects

Active projects or milestones with IDs and current status.

Syncing

Export current data from the tracker (teams, labels, projects, statuses), compare against the existing reference, and update. Record changes in a workspace memory entry.

Supported Trackers

Any tracker that provides exportable teams, labels, statuses, and projects: Linear, GitHub Issues, Jira, Asana, Shortcut, ClickUp, Notion, Azure DevOps

Eval Infrastructure

Record and enforce project-specific rules/conventions as atomic evals. Each eval validates ONE rule through multiple test functions, can be deterministically checked, and automatically creates tasks when violations are detected.

Supported Languages

Language	Base Class	Runner	Templates
Python	eval_base.py	run-evals.py	evals/templates/python/
Dart	eval_base.dart	run_evals.dart	evals/templates/dart/
TypeScript	eval_base.ts	run-evals.ts	evals/templates/typescript/

Auto-Fix

Evals can optionally provide auto-fix functions for failing tests. When a test fails and has a corresponding fix function, the fix is applied and all tests are re-run.

How It Works

1. Each BaseEval subclass can override the fixes property/getter to return a mapping of test names to fix functions
2. Each fix function receives the violations string and should attempt to fix the underlying issue
3. After fixes are applied, ALL tests are re-run
4. If re-run passes: the eval exits with code 2 (review required)
5. If re-run fails: the eval exits with code 1 (definitive fail)

Exit Codes

Code	Meaning	Runner Behavior
0	All tests pass	Count as passed
1	Tests fail (with or without attempted fixes)	Count as failed
2	All tests pass AFTER auto-fix	Count as auto-fixed, exit non-zero

Runner Behavior with Auto-Fix

When any eval returns exit code 2:

• The runner continues executing ALL remaining evals (no early abort)
• The runner prints structured review/verification instructions at the end
• The runner exits with non-zero code regardless of whether all fixes succeeded
• The instructions direct both humans and AI agents to review the changes

Interface

Python:

@property
def fixes(self) -> Dict[str, Callable[[str], None]]:
    return {
        "test_example": self._fix_example,
    }

def _fix_example(self, violations: str):
    # Fix the issue based on violations string
    pass

Dart:

@override
Map<String, FixFunction> get fixes => {
      'test_example': _fixExample,
    };

Future<void> _fixExample(String violations) async {
  // Fix the issue based on violations string
}

TypeScript:

get fixes(): Record<string, FixFunction> {
  return {
    test_example: (violations) => this.fixExample(violations),
  };
}

private async fixExample(violations: string): Promise<void> {
  // Fix the issue based on violations string
}

When NOT to Use Auto-Fix

Auto-fix is optional. Do not provide fixes for evals where:

• The fix is non-deterministic or context-dependent (e.g. all-tests-pass)
• The fix requires human judgment
• The eval checks something that cannot be programmatically corrected

Default Validation Eval

One validation eval is installed by default during /init-*-evals:

Eval	What	Configuration
all-tests-pass	Runs project tests	Configure test_command in eval.json

all-tests-pass

Runs the configured test command and validates exit code is 0.

Configuration required: Update test_command in eval.json:

{
  "test_command": ["dart", "test"]
}

Common test commands:

• Dart: ["dart", "test"]
• Flutter: ["flutter", "test"]
• Python/pytest: ["python3", "-m", "pytest", "-q"]
• Node.js: ["npm", "test"]
• Vitest: ["npx", "vitest", "run"]
• Go: ["go", "test", "./..."]
• Rust: ["cargo", "test"]
• Make: ["make", "test"]

Push Protection (Pre-push Hook)

The optional pre-push hook provides two checks before allowing a push:

1. Run all evals - Creates task files for any violations
2. Check for eval tasks - Blocks push if any eval task files exist

An eval task is identified by having BOTH in frontmatter:

• type: task
• eval: field

Regular task files (without both fields) are ignored.

The hook is installed to .git/hooks/pre-push and runs automatically before each push.

Makefile Integration

The init commands create a Makefile with standardized targets:

.PHONY: ready evals

# Default target: run all validation steps
ready: evals
	@echo "✓ All checks passed!"

# Run evals to validate project conventions
evals:
	@npx tsx workspace/evals/run-evals.ts

• make ready - Comprehensive readiness check (runs evals)
• make evals - Run all eval validations

Eval Structure

Each eval lives in its own folder:

workspace/evals/{category}/{name}/
├── eval.md           # Documentation
├── eval.json         # Configuration
├── eval.py           # Python script (or eval.dart / eval.ts)
└── tests/
    └── test_eval.py  # pytest tests (or eval_test.dart / eval.test.ts)

Key concepts:

• Folder name IS the eval name
• Script contains multiple small test_* functions (Python), tests map (Dart), or tests getter (TypeScript)
• Each test function validates one specific condition
• BaseEval discovers and runs all tests
• Violations from all tests are aggregated
• Failed evals create tasks in workspace/tasks/
• Evals can optionally provide auto-fix functions via the fixes property

Constraints

• Each eval must validate ONE single rule
• Each rule is checked through multiple small test functions
• MUST create test file (eval is incomplete without tests)
• Task template must be discussed with user
• ALL evals MUST ignore workspace/ folder when scanning files