docs: add product workspaces and UX outline#26
Conversation
Reviewer's GuideAdds a comprehensive product workspaces and UX outline for AgentTower, defining the three-workspace model (Agent Operations, Project and Specs, Testing and Demo) plus handoff, drift, validation, and UI/data models to guide FEAT-012 planning. Flow diagram for the master-agent handoff UX modelflowchart TD
A[Start handoff] --> B[Select master_agent]
B --> C[Select project_repo]
C --> D[Select work_items]
D --> E[Suggest mode]
E --> F[Show helper_policy_defaults]
F --> G[Generate prompt_preview]
G --> H[Operator edits optional_notes]
H --> I[Submit handoff]
I --> J[Persist handoff_object]
J --> K[Link to master_project_features]
K --> L[End]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- You define a lot of concrete enums and field names for things like feature lifecycle, handoff objects, drift signals, and validation runs; consider explicitly calling out which of these are normative vs illustrative and aligning their naming style with existing backend models (e.g., snake_case vs camelCase) to reduce future mismatch when they’re implemented.
- There are a few terminology inconsistencies (e.g.,
SpeckitvsSpec Kit, capitalization ofOpenSpec,project/specsvsProject and Specs); standardizing these terms in this document now will make it easier to wire the three workspaces into a coherent UI later.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- You define a lot of concrete enums and field names for things like feature lifecycle, handoff objects, drift signals, and validation runs; consider explicitly calling out which of these are normative vs illustrative and aligning their naming style with existing backend models (e.g., snake_case vs camelCase) to reduce future mismatch when they’re implemented.
- There are a few terminology inconsistencies (e.g., `Speckit` vs `Spec Kit`, capitalization of `OpenSpec`, `project/specs` vs `Project and Specs`); standardizing these terms in this document now will make it easier to wire the three workspaces into a coherent UI later.
## Individual Comments
### Comment 1
<location path="docs/product-sections-and-control-panel.md" line_range="432-441" />
<code_context>
+- Spec Kit feature specs
</code_context>
<issue_to_address>
**question (typo):** Inconsistent naming between "Spec Kit" and "Speckit" may confuse readers
Here you use "Spec Kit" (e.g., "Spec Kit feature specs"), but later the tool is referred to as "Speckit". If they are the same tool, please standardize the spelling; if not, clarify the distinction between them.
Suggested implementation:
```
- Speckit feature specs
```
Search the rest of `docs/product-sections-and-control-panel.md` (and related docs, if appropriate) for both `Spec Kit` and `Speckit` and standardize on a single spelling (likely `Speckit` as the product name). Also update any headings, links, or references (e.g., "Spec Kit workspace", "Spec Kit docs") to use that same spelling for consistency.
</issue_to_address>
### Comment 2
<location path="docs/product-sections-and-control-panel.md" line_range="28-37" />
<code_context>
+- Docker bench-container discovery
</code_context>
<issue_to_address>
**suggestion (typo):** Use consistent spelling for "bench container" vs "bench-container"
This term appears both as “bench-container” and “bench container.” If they refer to the same concept, please pick one form and use it consistently to avoid confusion.
Suggested implementation:
```
- Docker bench container discovery
```
Search the rest of the codebase and docs for both “bench-container” and “bench container” and normalize them all to “bench container” (without a hyphen) wherever they refer to this same concept.
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
| - Spec Kit feature specs | ||
| - OpenSpec proposed changes | ||
|
|
||
| ### 4.1 Primary operator questions | ||
|
|
||
| This workspace should answer: | ||
|
|
||
| 1. Which project am I looking at? | ||
| 2. What is the current intended shape of this project? | ||
| 3. What feature or change is active right now? |
There was a problem hiding this comment.
question (typo): Inconsistent naming between "Spec Kit" and "Speckit" may confuse readers
Here you use "Spec Kit" (e.g., "Spec Kit feature specs"), but later the tool is referred to as "Speckit". If they are the same tool, please standardize the spelling; if not, clarify the distinction between them.
Suggested implementation:
- Speckit feature specs
Search the rest of docs/product-sections-and-control-panel.md (and related docs, if appropriate) for both Spec Kit and Speckit and standardize on a single spelling (likely Speckit as the product name). Also update any headings, links, or references (e.g., "Spec Kit workspace", "Spec Kit docs") to use that same spelling for consistency.
| - Docker bench-container discovery | ||
| - tmux pane discovery | ||
| - agent registration, roles, and capabilities | ||
| - safe queueing and prompt delivery | ||
| - routing and arbitration | ||
|
|
||
| This is the system underneath every other product layer. | ||
|
|
||
| ### 1.2 App backend contract | ||
|
|
There was a problem hiding this comment.
suggestion (typo): Use consistent spelling for "bench container" vs "bench-container"
This term appears both as “bench-container” and “bench container.” If they refer to the same concept, please pick one form and use it consistently to avoid confusion.
Suggested implementation:
- Docker bench container discovery
Search the rest of the codebase and docs for both “bench-container” and “bench container” and normalize them all to “bench container” (without a hyphen) wherever they refer to this same concept.
|
There was a problem hiding this comment.
Pull request overview
Adds a new draft productization document (docs/product-sections-and-control-panel.md) that reframes AgentTower around three operator workspaces (Agent Operations, Project and Specs, Testing and Demo) and outlines UX models, data objects (project cards, master summaries, handoffs, drift signals, validation targets/entrypoints/runs/demo readiness), a top-level UI nav outline, and a FEAT-012/FEAT-013/later delivery plan. The document is intended as grounded input for FEAT-012 planning.
Changes:
- Introduces a three-workspace product model and per-workspace UX outlines.
- Defines proposed structured object schemas for handoffs, drift signals, and validation/demo objects.
- Maps the outline to a concrete delivery order (FEAT-012 control panel, FEAT-013 managed sessions, later items).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - pending | ||
| - in_flight | ||
| - blocked | ||
| - expired | ||
| - cancelled | ||
| - delivered |
Summary
Why
This preserves the current productization thinking in-repo so FEAT-012 can use it as grounded input instead of relying on local-only notes.
Summary by Sourcery
Documentation: