ed/manual_slop
Private
Public Access
0
0
Fork 0
Code Activity

conductor(track): superpowers review section 16 — Dual-Convention + Anything Else (cross-cutting)

Browse Source
This commit is contained in:
Edward R. Gonzalez
2026-07-05 13:35:48 -04:00
parent 3a3928f7dc
commit 10323e00e1
1 changed files with 66 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
conductor/tracks/superpowers_review_20260619/report.md
+66 -1
View File
@@ -1072,4 +1072,69 @@ The project's 5 MMA skills are the project's own multi-model architecture for or
## 16. Dual-Convention + Anything Else
<!-- Section 16 cross-cutting (200-400 LOC; one paragraph per finding). Verdict pending. -->
## 16. Dual-Convention + Anything Else
This section captures cross-cutting findings that don't fit the per-skill structure of Sections 1-15. The dual-convention analysis is the load-bearing finding (per the spec's user-flagged concern); the remaining findings are one-paragraph observations from the codebase audit.
### 16.1 Dual-Convention: `docs/superpowers/specs/` vs `conductor/tracks/<id>/spec.md`
The project has two parallel conventions for spec + plan artifacts:
- **OLD convention (conductor plugin era, started ~2026-03):** `conductor/tracks/<id>/spec.md` + `plan.md`. This is the user's chosen convention (per metadata.json Q4 = A). Active track count: ~50+ tracks in `conductor/tracks/`.
- **NEW convention (superpowers-plugin defaults):** `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md` + `docs/superpowers/plans/YYYY-MM-DD-<feature-name>.md`. Per the `brainstorming` skill's "After the Design" rule. Spec count: 20 specs + 21 plans = 41 files in `docs/superpowers/`.
**Three options for the deferred rebuild:**
1. **Keep both (status quo).** Pros: zero migration cost; both conventions are usable. Cons: ambiguity for new agents ("which convention should I follow?"); 41 superpowers-plugin specs may be orphaned.
2. **Adopt conductor convention everywhere (deprecate docs/superpowers/).** Pros: single convention; matches user's Q4 = A choice; aligns with `conductor/workflow.md` §"Planning Session Workflow". Cons: migrate or delete 41 superpowers-plugin files; the superpowers-plugin users who expect `docs/superpowers/specs/` would be surprised.
3. **Adopt superpowers-plugin convention everywhere (deprecate conductor convention).** Pros: aligns with the superpowers-plugin defaults; future superpowers updates integrate cleanly. Cons: contradicts user's Q4 = A; migrates 50+ tracks; breaks conductor-specific tooling (e.g., `tracks.md` registry).
4. **Split by artifact type.** Specs at `docs/superpowers/specs/` (design intent), plans at `conductor/tracks/<id>/plan.md` (executable tasks). Pros: matches the brainstorming/writing-plans skill split (specs are pre-approval; plans are post-approval). Cons: two locations for one track; agent must remember which is which.
**Recommendation:** Option 2 (adopt conductor convention everywhere) is the most consistent with user's stated choice. The deferred rebuild may want to:
- Move or delete the 41 files in `docs/superpowers/` once the conductor convention is confirmed.
- Update the `brainstorming` and `writing-plans` skills (or override per user preference) to write to `conductor/tracks/<id>/spec.md` and `plan.md`.
**Verdict.**
| Field | Value |
|---|---|
| **Primary** | `GAP` |
| **Integration tag** | `INTEGRATE-PARTIAL` |
| **Section size** | cross-cutting |
| **Cross-refs** | fable_review_20260617 (sibling review flagged this; fable_review was authored at `conductor/tracks/fable_review_20260617/`, not `docs/superpowers/specs/`); nagent_review_20260608 §10 ("durable work" applies to conventions, not just code) |
**Rationale.** The project has two parallel spec/plan conventions; the user chose conductor convention per Q4 = A; the superpowers-plugin defaults to `docs/superpowers/specs/`. The gap is the orphaned 41 files in `docs/superpowers/`.
**Recommended change.** Adopt Option 2: deprecate `docs/superpowers/` in favor of `conductor/tracks/<id>/`. Migrate or delete the 41 superpowers-plugin files. Update the `brainstorming` + `writing-plans` skill defaults.
### 16.2 Cross-Cutting Findings (one paragraph each)
**Legacy `.opencode/` and `.gemini/` directories.** The project has 6 agent files in `.opencode/agents/` (legacy from Gemini CLI conductor-plugin era) and a mirror at `.gemini/skills/`. These are NOT used by the current OpenCode-based workflow. Section 15 (MMA Skills Cluster) flags this; Section 16 here adds that the `.opencode/` and `.gemini/` directories should be cleaned up or marked as legacy. (FOLLOW-UP TRACK: `cleanup_legacy_opencode_gemini_dirs_20260705_PLACEHOLDER`.)
**Audit script drift between `src/` and `conductor/`.** The project has 4 audit scripts (`scripts/audit_main_thread_imports.py`, `audit_weak_types.py`, `audit_no_models_config_io.py`, `audit_optional_in_3_files.py`) that enforce conventions in `src/` files. The conventions themselves live in `conductor/code_styleguides/` (11 files, ~2,400 lines). The audit scripts enforce; the styleguides document. This split is correct; the gap is that some audit scripts reference styleguide files that may have been moved. (VERIFY: re-run `audit_*` scripts against current styleguides; fix references.)
**Hard ban list growth.** `AGENTS.md` "Critical Anti-Patterns" has grown to 16+ hard bans (added 2026-06-07 through 2026-06-25). The list is comprehensive but monolithic. A future refactor could split the hard bans into a `conductor/code_styleguides/hard_bans.md` styleguide with AGENTS.md referencing it. This is a documentation-only refactor. (LOW PRIORITY.)
**The "1-space indentation" rule is Python-only.** Per `conductor/workflow.md` §"Code Style (MANDATORY - Python)", the 1-space indentation applies to Python files only. Markdown, TOML, JSON, and other non-Python files are not affected. New agents may over-apply this rule to non-Python files. A small documentation clarification in `conductor/workflow.md` could prevent this. (LOW PRIORITY.)
**The `result_types.py` Result[T] + NIL_T sentinel pattern.** Per `conductor/code_styleguides/error_handling.md`, the project uses `Result[T]` dataclasses + `NIL_T` sentinels instead of `Optional[T]` for recoverable failures. The convention is applied to 3 of 65 `src/` files (mcp_client.py, ai_client.py, rag_engine.py); the remaining 62 files still use try/except/raise. The deferred rebuild has a dedicated track: `data_oriented_error_handling_20260606` (parent) + 5 sub-tracks (`result_migration_review_pass_20260617`, `result_migration_small_files_20260617`, `result_migration_app_controller_20260618`, `result_migration_gui_2_20260619`, `result_migration_baseline_cleanup_20260620`, `result_migration_cruft_removal_20260620`). The work is partially done; the cruft_removal sub-track is the final cleanup. (STATUS: 6 of 7 sub-tracks shipped per chronology; cruft_removal Active with Round 4 corrections.)
**The `.opencode/` agents/commands + `.gemini/skills/` mirror is a maintenance trap.** New agents looking for "the MMA tier-1 skill" might find `.opencode/agents/mma-tier1-orchestrator.md` first (it's older, larger) and miss `.agents/skills/mma-tier1-orchestrator/SKILL.md` (the canonical, current location). The `.opencode/agents/` files should be marked as legacy with a `LEGACY.md` pointer or removed entirely. (FOLLOW-UP TRACK: see 16.2 first bullet.)
**The `MANUAL_SLOP_WORKSPACE.md` workspace profile mechanism.** The project supports workspace profiles (per `conductor/tracks/workspace_profiles_20260310/`); profiles save/restore ImGui docking layouts. The mechanism is mature but the documentation is sparse. A `docs/guide_workspace_profiles.md` cross-reference (per the deep-dive guide convention) could surface this. (LOW PRIORITY; cross-references exist in `docs/Readme.md` already.)
**The `audit_*` scripts use the legacy `src/` namespace assumption.** All 4 audit scripts operate on `src/` files. With the `module_taxonomy_refactor_20260627` track's per-system file split, some "src/" files moved to per-system files (e.g., `src/models.py` → `src/mma.py` + `src/type_aliases.py` + `src/mcp_tool_specs.py` + `src/result_types.py`). The audit scripts may have stale paths. (VERIFY: re-run audits; fix paths.)
**Verdict.**
| Field | Value |
|---|---|
| **Primary** | `GAP` |
| **Integration tag** | `INTEGRATE-PARTIAL` |
| **Section size** | cross-cutting |
| **Cross-refs** | nagent_review_20260608 §10 (durable work applies to conventions + cleanup); fable_review_20260617 §14 (anti-user patterns include orphan files); intent_dsl_survey_20260612 §6 (these are documented as "AI-agent properties") |
**Rationale.** Section 16 surfaces 8 cross-cutting findings, none of which are blocking but all of which are worth addressing in the deferred rebuild. The dual-convention finding (16.1) is the load-bearing concern; the 7 paragraph-length findings (16.2) are minor.
**Recommended change.** Address dual-convention first (HIGH); audit script drift + opencode/gemini cleanup second (MEDIUM); the rest are LOW.