You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Compressed for calm, boring, operator-first tone. Changes mapped to your list:
1. Opening — say each thing once
Single screen: workflow bullets → anchor → why (chat vs JoyZoning) → what it is not → audience → two arrow links. No repeated blockquotes, no second “not a second IDE” line, no diet-hermes in the hero.
2. JSDP — advanced, at the bottom
New section “Advanced — multi-role delivery (optional)” after Stuck. Removed from the four-step table and Phase 3 paths.
3. Less manifesto vocabulary
Dropped cognition, convergence, philosophy links in the main path, lease/orchestration in user-facing tables. philosophy.md only linked under Advanced.
4. Added “why”
One short paragraph: most agents stop at chat; JoyZoning adds tracking, repo execution, verify, audit, controlled merge.
5. Plain language
“Task activity” instead of execution viewport
“Ready for your review” instead of lease jargon
“One active task run per card” instead of lease
“Step” instead of “Phase” in headings (lighter weight)
Removed extra mermaid diagrams in the main path
6. Workflow tool framing
Shorter sections, tables only where they help, habits as one line, contributor/docs at the end.
Kept: “Trust Workspace, not chat, for sign-off” in Step 2.
Kept: “Chat plans. Workspace is truth.” once at the top.
@@ -13,203 +13,135 @@ JoyZoning is a local cockpit for agent work:
13
13
- Verify with tests and builds
14
14
- Merge only when you approve
15
15
16
-
> **What it is not**
17
-
>
18
-
> - Not a second IDE
19
-
> - Not an autonomous auto-merge bot
20
-
> - Not “the agent said it’s done”
16
+
Chat plans. Workspace is truth.
21
17
22
-
**For operators who want evidence before completion.**
18
+
Most coding agents stop at chat. JoyZoning adds task tracking, real repo execution, verification workflows, audit trails, and merge only when you approve — so work stays reviewable before it becomes “done.”
23
19
24
-
> Chat plans; Workspace is truth.
20
+
JoyZoning is not:
25
21
26
-
> **New here?**[What's next](docs/onboarding/whats-next.md) (~20 min after install) · [Onboarding hub](docs/onboarding/README.md)
22
+
- a second IDE
23
+
- an autonomous auto-merge bot
24
+
- “the agent said it’s done”
27
25
28
-
---
29
-
30
-
## Onboarding in four steps
31
-
32
-
```mermaid
33
-
flowchart LR
34
-
P0[Phase 0 — Decide] --> P1[Phase 1 — Install]
35
-
P1 --> P2[Phase 2 — First merge]
36
-
P2 --> P3[Phase 3 — Scale]
37
-
```
26
+
For operators who want evidence before completion.
38
27
39
-
| Phase | Goal | Time | Go to |
40
-
|-------|------|------|--------|
41
-
|**0 — Decide**| Confirm JoyZoning matches your workflow |~5 min |[Before you begin](docs/onboarding/before-you-begin.md)|
42
-
|**1 — Install**| App running, health grade visible, repo opened |~15 min |[5-minute quickstart](docs/onboarding/quickstart.md)|
43
-
|**2 — First merge**| One card: dispatch → verify → merge → Complete |~20 min |**[What's next](docs/onboarding/whats-next.md)** ← main walkthrough |
|Supervise agents on a **real repo**with an audit trail | Yes|
55
-
|**Approve**what ships (diff + tests + your sign-off)|Yes|
56
-
|Replace your IDE or use only chat | No — keep Cursor/VS Code; JoyZoning is the**cockpit**|
57
-
|Unattended auto-merge with no human gate | No — merge is always operator-owned|
35
+
|Step | Goal|Time | Guide|
36
+
|------|------|------|--------|
37
+
|**0 — Decide**| Is this the workflow you want? |~5 min |[Before you begin](docs/onboarding/before-you-begin.md)|
38
+
|**1 — Install**| App running, repo opened |~15 min|[Quickstart](docs/onboarding/quickstart.md)|
39
+
|**2 — First merge**| Dispatch → verify → merge → Complete |~20 min |**[What's next](docs/onboarding/whats-next.md)**|
40
+
|**3 — Daily use**| Desktop, CLI, or both | ongoing |[Setup checklist](docs/onboarding/setup-checklist.md)|
58
41
59
-
**Still unsure?**[Before you begin](docs/onboarding/before-you-begin.md) · [What is JoyZoning?](docs/what-is-joyzoning.md) (plain English)
42
+
---
60
43
61
-
### Mental model (read once — used in every step)
44
+
##Step 0 — Fit check
62
45
63
-
1.**Chat plans; Workspace is truth** — Manager Chat = thinking; **Workspace** = files on disk (like a PR “Files changed” tab). Trust Workspace, not chat, for sign-off.
64
-
2.**One card → one branch** — You open one project folder. After **Dispatch**, work is on `joyzoning/card-<task-id>` in that folder (no hidden sandbox copy).
65
-
3.**Only you merge** — Agents stop at `ready_for_review`; **Complete** is yours after review (and verification if you run it).
46
+
| You want… | Good fit? |
47
+
|-----------|-----------|
48
+
| Supervised agent work on a **real repo** with an audit trail | Yes |
49
+
| Review diffs and tests before anything ships | Yes |
50
+
| A replacement IDE or chat-only workflow | No — keep your editor; use JoyZoning to supervise |
66
51
67
-
[Full philosophy](docs/philosophy.md) · [Which folder am I viewing?](docs/workspace-state.md)
52
+
[What is JoyZoning?](docs/what-is-joyzoning.md) (plain English)
**Ready for Step 2 when:** app open, health not **Blocked**, your repo selected (**Project → Open Workspace**). First Hermes setup may take a few minutes.
105
69
106
70
---
107
71
108
-
## Phase 2 — Your first supervised task
72
+
## Step 2 — First task (dispatch → merge)
109
73
110
-
This is the habit you will repeat for every card. **Step-by-step with screenshots-level detail:**[What's next after setup](docs/onboarding/whats-next.md).
74
+
Full walkthrough: **[What's next](docs/onboarding/whats-next.md)**.
111
75
112
-
```mermaid
113
-
flowchart LR
114
-
P[Plan] --> K[Kanban]
115
-
K --> D[Dispatch]
116
-
D --> W[Work]
117
-
W --> V[Verify]
118
-
V --> R[ready_for_review]
119
-
R --> M[You merge]
120
-
```
76
+
| Step | Where | What you do | Done when… |
77
+
|------|--------|-------------|------------|
78
+
|**Plan**| Manager Chat | Describe the work | You have a reply |
79
+
|**Track**| Kanban | Create or pick a card | Card is on the board |
80
+
|**Dispatch**| Kanban | Start the agent on that card | Task activity shows a run |
81
+
|**Review files**| Workspace | Check changed files | You see the real diff |
82
+
|**Verify**| Workspace or `jz`| Run tests/build you care about | Status is ready for your review |
83
+
|**Merge**| Workspace → Kanban | Approve the change | Card is **Complete**|
121
84
122
-
| Step | Open in app | You do | Success signal |
123
-
|------|-------------|--------|----------------|
124
-
|**1. Plan**|**Manager Chat**| Describe the outcome; optional **→ Task**| Assistant replies (needs API key) |
125
-
|**2. Track**|**Kanban**| Create or select a card; use **Low** risk while learning | Card visible on board |
**Menus, not terminal:**[desktop menu guide](docs/onboarding/desktop-menu-guide.md) · **Glossary:**[plain-language](docs/onboarding/plain-language-glossary.md)
After the basic loop feels natural, you can run **sequential roles** on one repo (e.g. product → architecture → implementation → QA) with a merge between each role. Same repo throughout; one role at a time.
192
127
193
-
## Stuck?
128
+
```bash
129
+
./scripts/role-chain-dispatch.sh --create --workspace /path/to/repo --program "My App"
130
+
./scripts/role-chain-dispatch.sh --next
131
+
jz task complete<task-id> --yes
132
+
```
194
133
195
-
| Symptom | Fix |
196
-
|---------|-----|
197
-
| App won't open |[Setup troubleshooting](docs/onboarding/troubleshooting-setup.md)|
198
-
| Red **API** or **Dashboard** chip |[status-indicators](docs/onboarding/status-indicators.md)|
199
-
| Manager Chat never replies |[api-keys-and-models](docs/onboarding/api-keys-and-models.md)|
200
-
| Workspace empty after agent worked | Card not **Dispatched** — dispatch, re-select card |
0 commit comments