# Trae Workspace Tool P0 Execution Plan

## Objective

Refactor the current ops-only CLI into `trae-workspace-tool`, a Trae IDE enterprise intranet workspace generator with a multi-pack architecture. P0 ships only `internal-basic` profile plus `ops` pack, while making the code ready for future role packs.

## Current Constraints

- Runtime must remain zero third-party dependencies.
- Python requires `>=3.13`.
- New generated Rules must include `alwaysApply: true`.
- New generated Skills must include `name:` frontmatter.
- Generated scripts must default to read-only or dry-run.
- `REQUIRED_FILES` and template registration must stay synchronized or be replaced by an equivalent registry-derived source of truth.
- Current `.venv` is invalid for this host and must be rebuilt before final validation.

## What Already Exists

- `src/trae_workspace_tool/cli.py`: argparse CLI with `init`, `doctor`, `list-profiles`, and `list-packs`.
- `src/trae_workspace_tool/generator.py`: install and doctor logic.
- `src/trae_workspace_tool/templates.py`: generated asset templates.
- `tests/test_generator.py`: unit tests and generated script integration tests.
- `docs/specs/ops-maintenance-workspace.md`: original ops-only workspace spec.
- Current ops templates are useful and should become the first pack instead of being discarded.

## NOT in Scope

- Dev, QA, business consultant, PM, or BA packs.
- Runtime plugin loading.
- Enterprise-specific config file parsing.
- Real script execution.
- PyPI publishing.
- CI setup, unless it is needed to restore local validation confidence.
- Removing old generated ops asset paths from target projects.

## Architecture

P0 should use a small static registry.

```text
CLI
 ├── parse command
 ├── resolve profile name, default internal-basic
 ├── resolve pack name, default ops
 └── call workspace installer / doctor

Registry
 ├── profiles["internal-basic"]
 │    └── enterprise safety assets + validators
 └── packs["ops"]
      └── ops assets + validators

Installer
 ├── flatten selected profile assets + selected pack assets
 ├── create parent directories
 ├── skip existing files unless force
 └── chmod executable generated scripts

Doctor
 ├── flatten selected profile assets + selected pack assets
 ├── check files exist
 ├── run asset validators
 └── return present / missing / invalid report
```

Suggested modules:

```text
src/trae_workspace_tool/
  __init__.py
  cli.py
  generator.py
  models.py
  registry.py
```

Keep this boring. Do not add a plugin framework in P0.

## Implementation Phases

### Phase 0: Restore Local Validation Environment

Actions:

1. Rebuild `.venv` for the current architecture.
2. Confirm `uv run python --version` uses a runnable Python 3.13 interpreter.
3. Run the current test suite before code changes if possible.

Acceptance:

```bash
uv run pytest -q
```

If rebuilding `.venv` is outside the current patch scope, record the blocker and continue with `PYTHONPATH=src python3 -m pytest -q` only as a temporary diagnostic.

### Phase 1: Rename Package and CLI

Actions:

1. Use package directory `src/trae_workspace_tool/`.
2. Update imports in tests.
3. Update `pyproject.toml`:
   - project name to `trae-workspace-tool`
   - script `trae-workspace-tool = "trae_workspace_tool.cli:main"`
   - hatch package path to `src/trae_workspace_tool`
4. Do not expose a compatibility CLI alias.
5. Update README command examples.

Risk:

- Package rename can break imports and entry points.

Mitigation:

- Use tests and smoke commands to verify the new command.

### Phase 2: Introduce Registry Data Model

Actions:

1. Add minimal dataclasses:
   - `Asset`
   - `Profile`
   - `Pack`
   - `ValidationIssue`
2. Add static registry:
   - `get_profile("internal-basic")`
   - `get_pack("ops")`
   - `list_profiles()`
   - `list_packs()`
3. Replace hardcoded `REQUIRED_FILES` with registry-derived expected assets, or keep `REQUIRED_FILES` as a compatibility view generated from selected default profile plus pack.
4. Keep template functions in `generator.py` until the registry is stable. Do not split every template into new modules unless the file becomes hard to maintain.

Acceptance:

- Existing install behavior still works through default profile plus ops pack.
- No runtime dependencies added.

### Phase 3: Add `internal-basic` Profile

Actions:

1. Add `.trae/rules/enterprise-safety.md`.
2. Include required enterprise policy:
   - no secrets reading
   - no data exfiltration
   - human approval for production changes
   - default read-only/dry-run posture
   - path containment for scripts
3. Add validator:
   - file exists
   - contains `alwaysApply: true`
   - contains key safety phrases or structured markers

Acceptance:

- `init --profile internal-basic --pack ops` creates enterprise safety rule.
- `doctor` fails if `enterprise-safety.md` is missing or lacks `alwaysApply: true`.

### Phase 4: Convert Existing Ops Assets Into `ops` Pack

Actions:

1. Register current ops assets under the `ops` pack.
2. Preserve current file paths.
3. Add validators:
   - ops rule has `alwaysApply: true`
   - ops skill has `name: ops-maintenance-automation`
   - maintenance script contains root containment helper
   - maintenance script defaults to dry-run behavior
4. Ensure no-overwrite and `--force` still behave exactly as before.

Acceptance:

- Existing ops tests pass after updating imports and expected file list.
- Current target project output is additive: existing ops files are still generated.

### Phase 5: Fix Dry-Run Semantics

Actions:

1. Change generated `maintenance_check.py` so dry-run is the default.
2. Keep `--dry-run` as a no-op compatibility flag.
3. Add `--execute` only if it is explicitly non-operational in P0, or defer it entirely.
4. Ensure stale project candidates show planned action without implying mutation.
5. Ensure no code path moves, deletes, restarts, or changes config.

Recommended P0 behavior:

```bash
python3 scripts/maintenance_check.py --root /tmp/demo-project
```

prints dry-run planning output and performs no writes.

Acceptance:

- Tests prove no `--dry-run` argument is required to get safe dry-run output.
- `--dry-run` still works.
- No test expects real execution.

### Phase 6: Expand CLI

Actions:

1. Add parser options:
   - `init --profile`
   - `init --pack`
   - `doctor --profile`
   - `doctor --pack`
2. Add commands:
   - `list-packs`
   - `list-profiles`
3. Unknown profile or pack exits non-zero with a concise message and no traceback.

Acceptance:

```bash
uv run trae-workspace-tool list-packs
uv run trae-workspace-tool list-profiles
uv run trae-workspace-tool init --target /tmp/demo-project
uv run trae-workspace-tool doctor --target /tmp/demo-project
```

### Phase 7: Upgrade Doctor Reports

Actions:

1. Extend doctor result to include:
   - present
   - missing
   - invalid
2. Keep CLI output simple:
   - `present: path`
   - `missing: path`
   - `invalid: path: reason`
3. Return `1` if any required asset is missing or invalid.

Acceptance:

- Corrupting a generated rule by removing `alwaysApply: true` makes `doctor` fail.
- Corrupting a skill by removing `name:` makes `doctor` fail.

### Phase 8: Update Documentation

Actions:

1. Update README positioning:
   - Trae IDE enterprise intranet workspace generator
   - current P0 supports internal-basic profile and ops pack
2. Keep old ops spec as historical source.
3. Link to the new spec and this execution plan.
4. Document rename and old command compatibility policy.
5. Document enterprise usage workflow:
   - install tool
   - run init
   - run doctor
   - open Trae
   - verify Rules and Skills
   - create Agent from prompt

Acceptance:

- README examples use `trae-workspace-tool`.
- README clearly says only ops pack exists in P0.

## Test Plan

### Unit Tests

Add or update tests for:

- Registry lists `internal-basic`.
- Registry lists `ops`.
- Default selected assets include profile and pack assets.
- Selected profile and pack assets fail fast on duplicate relative paths.
- Unknown profile raises a clear error.
- Unknown pack raises a clear error.
- `init` creates enterprise safety rule.
- `doctor` reports enterprise safety rule missing.
- `doctor` reports missing `alwaysApply: true`.
- `doctor` reports missing Skill `name:`.
- `--force` overwrites selected profile and pack assets.
- No-overwrite skips selected profile and pack assets.

### Generated Script Integration Tests

Add or update tests for:

- Default run without `--dry-run` prints dry-run plan.
- `--dry-run` remains accepted.
- Invalid root returns `1`.
- Missing backup/logs/projects produces warnings.
- Oversized logs produce warning.
- Custom directories work.
- Excluded project directories are skipped.
- Planned archive targets remain inside root.

### CLI Smoke Tests

Run:

```bash
uv run trae-workspace-tool list-packs
uv run trae-workspace-tool list-profiles
uv run trae-workspace-tool init --target /tmp/demo-project
uv run trae-workspace-tool doctor --target /tmp/demo-project
python3 /tmp/demo-project/scripts/maintenance_check.py --root /tmp/demo-project
```

### Full Validation

Run:

```bash
uv run pytest -q
uv run ty check src tests
uv run ruff check src tests
```

## Coverage Diagram

```text
CODE PATHS                                      TEST REQUIREMENTS
CLI
  ├── init(default profile+pack)                unit + smoke
  ├── init(explicit profile+pack)               unit
  ├── init(unknown profile)                     unit
  ├── init(unknown pack)                        unit
  ├── doctor(valid workspace)                   unit + smoke
  ├── doctor(missing asset)                     unit
  ├── doctor(invalid rule/skill)                unit
  ├── list-packs                                unit + smoke
  └── list-profiles                             unit + smoke

Registry
  ├── internal-basic profile assets             unit
  ├── ops pack assets                           unit
  └── selected asset flattening                 unit

Installer
  ├── create new files                          existing + update
  ├── skip existing without force               existing
  ├── overwrite with force                      existing
  └── chmod generated script                    existing + update if needed

Doctor
  ├── present/missing                           existing + update
  ├── rule frontmatter validation               new unit
  ├── skill frontmatter validation              new unit
  └── script safety validation                  new unit

Generated maintenance script
  ├── default dry-run                           new integration
  ├── explicit --dry-run                        update integration
  ├── invalid root                              existing
  ├── custom dirs                               existing
  ├── excludes                                  existing
  └── warning exit codes                        existing + update semantics
```

## Failure Modes

| Failure mode | Mitigation | Test |
|--------------|------------|------|
| Rename breaks CLI entry point | Document and test the supported CLI command | CLI smoke |
| Registry and doctor expected files drift | Derive expected files from selected profile and pack | Unit |
| Enterprise rule generated without `alwaysApply` | Asset validator | Unit |
| Skill generated without `name:` | Asset validator | Unit |
| Generated script appears to support real execution | Default dry-run and no write code path | Integration |
| Unknown pack silently ignored | Explicit registry lookup error | Unit |
| Existing user files overwritten | Preserve no-overwrite default | Existing unit |
| Local validation blocked by wrong-arch venv | Rebuild `.venv` before final validation | Manual validation |

## Parallelization Strategy

Sequential implementation is recommended for P0. The rename touches imports, pyproject, tests, docs, and CLI behavior, so parallel worktrees would create avoidable conflicts.

If split later:

```text
Lane A: package rename + CLI entry points
Lane B: registry model and profile/pack selection
Lane C: doctor validators and tests
Lane D: documentation

Execution order:
  A -> B -> C -> D
```

Lane B depends on A because imports and package paths change. Lane C depends on B because validators need selected profile/pack assets.

## Rollback Strategy

1. If package rename fails, revert to the previous package boundary in a follow-up fix.
2. If registry abstraction destabilizes install behavior, keep current `_template_map()` and wrap it as the `ops` pack in a compatibility layer.
3. If doctor validation is too brittle, ship existence checks plus rule/skill frontmatter validation only, and defer script semantic validation to P1.
4. If dry-run semantics change breaks tests, update behavior first and preserve `--dry-run` as accepted compatibility syntax.

## Definition of Done

1. New spec and execution plan are committed.
2. Package and CLI use `trae-workspace-tool` without a compatibility alias.
3. `internal-basic` profile exists and generates enterprise safety rule.
4. `ops` pack generates all existing ops assets.
5. `init` and `doctor` accept default and explicit profile/pack arguments.
6. `list-packs` and `list-profiles` work.
7. Generated maintenance script is dry-run by default.
8. Tests cover registry, CLI, doctor validators, and generated script semantics.
9. `uv run pytest -q` passes.
10. `uv run ty check src tests` passes.
11. `uv run ruff check src tests` passes.
12. Smoke install and doctor pass against `/tmp/demo-project`.
