npm - vibe-coding-master - Versions diffs - 0.0.6 → 0.0.8 - Mend

vibe-coding-master 0.0.6 → 0.0.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (50) hide show

package/README.md +207 -66
package/dist/backend/adapters/filesystem.js +13 -0
package/dist/backend/adapters/git-adapter.js +79 -1
package/dist/backend/adapters/translation-provider.js +145 -0
package/dist/backend/api/artifact-routes.js +16 -7
package/dist/backend/api/harness-routes.js +22 -0
package/dist/backend/api/message-routes.js +2 -0
package/dist/backend/api/project-routes.js +3 -8
package/dist/backend/api/task-routes.js +14 -0
package/dist/backend/api/translation-routes.js +70 -0
package/dist/backend/runtime/node-pty-runtime.js +20 -18
package/dist/backend/server.js +33 -2
package/dist/backend/services/app-settings-service.js +128 -0
package/dist/backend/services/artifact-service.js +7 -4
package/dist/backend/services/claude-transcript-service.js +509 -0
package/dist/backend/services/command-dispatcher.js +4 -2
package/dist/backend/services/harness-service.js +196 -0
package/dist/backend/services/message-service.js +1 -1
package/dist/backend/services/project-service.js +50 -9
package/dist/backend/services/session-service.js +13 -9
package/dist/backend/services/status-service.js +79 -1
package/dist/backend/services/task-service.js +118 -4
package/dist/backend/services/translation-prompts.js +173 -0
package/dist/backend/services/translation-queue.js +39 -0
package/dist/backend/services/translation-service.js +546 -0
package/dist/backend/templates/handoff.js +32 -0
package/dist/backend/templates/harness/architect-agent.js +12 -0
package/dist/backend/templates/harness/claude-root.js +14 -0
package/dist/backend/templates/harness/coder-agent.js +11 -0
package/dist/backend/templates/harness/gitignore.js +9 -0
package/dist/backend/templates/harness/project-manager-agent.js +14 -0
package/dist/backend/templates/harness/reviewer-agent.js +13 -0
package/dist/backend/ws/translation-ws.js +35 -0
package/dist/shared/types/harness.js +1 -0
package/dist/shared/types/translation.js +5 -0
package/dist/shared/validation/artifact-check.js +15 -1
package/dist/shared/validation/language-detect.js +46 -0
package/dist-frontend/assets/index-CuiNNOzj.css +32 -0
package/dist-frontend/assets/index-D59GuHCR.js +58 -0
package/dist-frontend/index.html +2 -2
package/docs/cc-best-practices.md +109 -40
package/docs/product-design.md +370 -1374
package/docs/v1-architecture-design.md +595 -1114
package/docs/v1-implementation-plan.md +898 -1603
package/package.json +1 -1
package/scripts/verify-package.mjs +8 -0
package/dist/backend/templates/role-messaging-context.js +0 -44
package/dist-frontend/assets/index-Bah6k-Ix.css +0 -32
package/dist-frontend/assets/index-EMaQuIB6.js +0 -58
package/docs/v1-message-bus-orchestration-design.md +0 -534

package/dist-frontend/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VibeCodingMaster</title>
-    <script type="module" crossorigin src="/assets/index-EMaQuIB6.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-Bah6k-Ix.css">
+    <script type="module" crossorigin src="/assets/index-D59GuHCR.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-CuiNNOzj.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/cc-best-practices.md CHANGED Viewed

@@ -68,6 +68,7 @@ Recommended structure:
 ```text
 repo/
   CLAUDE.md
+  .gitignore
   docs/
     ARCHITECTURE.md
@@ -95,6 +96,7 @@ repo/
     commands/
   .ai/
+    vcm/                 # ignored local VCM control state
     task-specs/
     handoffs/
       <task-slug>/
@@ -137,7 +139,7 @@ Minimum baseline for non-trivial AI coding:
 - root `CLAUDE.md`
 - module-local `CLAUDE.md` for edited modules
 - architecture, module map, testing, security, and dependency docs
-- role agents for project management/user communication/translation, architecture/planning, coding, and independent review/testing
+- role agents for project management/user communication, architecture/planning, coding, and independent review/testing
 - task specs, handoff artifacts, progress state, decisions, validation logs, known issues, and generated context artifacts
 - fast, changed-file, module, boundary, public-surface, contract-test, generated-artifact, docs-freshness, and agent-rule checks
 - hooks or CI gates for protected files, validation, docs sync, public contracts, and test quality
@@ -198,10 +200,10 @@ Root template:
 Role-specific behavior lives in `.claude/agents/`.
-- Use `claude --agent project-manager` for user communication, translation, task clarification, task specs, role routing, role commands, status summaries, and final acceptance.
-- Use `claude --agent architect` for architecture plans, module boundaries, file responsibilities, public contracts, test contracts, and phase plans.
+- Use `claude --agent project-manager` for user communication, task clarification, task specs, role routing, role commands, status summaries, and final acceptance.
+- Use `claude --agent architect` for architecture plans, module boundaries, file responsibilities, public contracts, test contracts, phase plans, and post-review docs sync / architecture drift checks.
 - Use `claude --agent coder` for implementation and direct tests within an approved plan.
-- Use `claude --agent reviewer` for independent review, test adequacy, validation evidence, docs sync, and acceptance findings.
+- Use `claude --agent reviewer` for independent review, test adequacy, validation evidence, docs gap detection, and acceptance findings.
 - Do not use an untagged session as an implicit project manager for non-trivial work.
 - Do not simulate another role inside the wrong session.
@@ -209,13 +211,33 @@ Role-specific behavior lives in `.claude/agents/`.
 - For complex features, cross-module changes, refactors, public API changes, schema changes, auth, payment, permission, or security-sensitive work, start Claude Code with an explicit role: `claude --agent <role>`.
 - Default core roles are `project-manager`, `architect`, `coder`, and `reviewer`.
-- The `project-manager` role owns user communication, translation, task routing, role commands, handoff verification, and final status reporting.
+- The `project-manager` role owns user communication, task routing, role commands, handoff verification, final status reporting, and PR preparation after required gates pass.
 - Do not let one coding session own architecture/plan decisions, implementation, final testing responsibility, and review.
 - Role outputs are exchanged through `.ai/handoffs/<task-slug>/`, not through chat history.
 - When the required role route includes `architect`, coding must not start until the architecture and plan artifact exists.
 - If the current session was not started with the required role, stop and ask the user to restart with `claude --agent <role>`; do not pretend to be that role inside the wrong session.
 - Critical global rules may be repeated in role agent files for defense in depth, but repeated rules must use stable rule IDs and be checked by `tools/check-agent-rules`. Do not maintain untracked manual copies.
+## VCM Managed Harness Blocks
+If VibeCodingMaster or another harness manager maintains project rules, those rules must live in repo-local files and be reviewable in Git. Do not inject long-lived collaboration rules into a Claude Code terminal as ordinary input.
+Allowed managed block format:
+```md
+<!-- VCM:BEGIN version=1 -->
+VCM-managed rules.
+<!-- VCM:END -->
+```
+Rules:
+- VCM may create missing `CLAUDE.md` and `.claude/agents/{project-manager,architect,coder,reviewer}.md` from recommended defaults.
+- If a file already exists, VCM may only insert or replace the VCM managed block.
+- VCM must not overwrite user-authored content outside managed blocks.
+- After applying harness changes, VCM must report changed files and recommend a user review/commit.
+- Session startup should pass environment variables and start the role agent; it should not paste a long VCM context into the terminal.
 ## Default Behavior
 - State assumptions before coding; ask when requirements, boundaries, or acceptance criteria are unclear.
@@ -241,7 +263,7 @@ Role-specific behavior lives in `.claude/agents/`.
 - Required validation passes.
 - New or modified public functions have contract tests.
 - Behavior changes have regression tests unless impractical.
-- Plan, architecture, public contract, test strategy, and module responsibility changes are reflected in docs.
+- Plan, architecture, public contract, test strategy, and module responsibility changes are reflected in docs after post-review architect docs sync.
 - Follow-ups are recorded in `.ai/state/known-issues.md` or the execution plan.
 ```
@@ -418,6 +440,7 @@ Explore
   -> implement phase 1
   -> validate
   -> review
+  -> architect docs sync / architecture drift check
   -> commit
   -> implement next phase
 ```
@@ -537,7 +560,7 @@ Do not include:
 For large projects, the default execution model should be explicit role-based sessions, not dynamic role routing inside one generic Claude conversation.
-The user-facing task should start with a `project-manager` role session. The project manager owns user communication, translation, role command dispatch, severity classification, role routing, progress tracking, and process verification. It does not own architecture, coding, and independent review for the same non-trivial task.
+The user-facing task should start with a `project-manager` role session. The project manager owns user communication, role command dispatch, severity classification, role routing, progress tracking, and process verification. It does not own architecture, coding, and independent review for the same non-trivial task.
 Do not make one generic Claude session own architecture, planning, coding, final testing, and review for non-trivial work. That blurs responsibility and makes acceptance weak.
@@ -554,7 +577,7 @@ Project manager responsibilities:
 ```text
 communicate with user
   -> clarify task
-  -> translate user intent into a task brief / task spec
+  -> turn user intent into a task brief / task spec
   -> classify severity
   -> choose required role route
   -> prepare the next role command
@@ -562,12 +585,14 @@ communicate with user
   -> start or ask the user to start architect/coder/reviewer/specialist sessions when needed
   -> track progress, blockers, validation, docs sync, and Replan
   -> verify role outputs and handoff artifacts
+  -> request post-review architect docs sync when required
+  -> prepare commit and submit the PR only after review and docs sync gates pass
   -> summarize final status and risks to the user
 ```
 The project manager is a process owner, not an execution owner.
-It is also the communication bridge between the user and the role agents. The user should not need to know how to write a perfect Claude Code prompt. The project manager owns the translation from user intent to precise agent instructions.
+It is also the communication bridge between the user and the role agents. The user should not need to know how to write a perfect Claude Code prompt. The project manager owns the conversion from user intent to precise agent instructions.
 It may route T0/T1 work to a lightweight coder flow when the task is small, scoped, and low risk. For non-trivial work, it coordinates role sessions and verifies the process.
@@ -616,9 +641,16 @@ coder command:
 reviewer command:
   read task spec, architecture-plan.md, implementation-log.md, validation-log.md, and git diff
-  verify scope, architecture, public contract, tests, validation, and docs sync
+  verify scope, architecture, public contract, tests, validation, and docs gaps
   write review-report.md
   only apply small, local, low-risk review-scoped fixes
+architect docs-sync command:
+  read task spec, architecture-plan.md, implementation-log.md, validation-log.md, review-report.md, and git diff
+  verify whether the final code still matches the approved architecture and public contracts
+  update architecture/module/testing/security docs when the code change made them stale
+  write docs-sync-report.md with docs changed, docs intentionally unchanged, and remaining doc risks
+  stop and request Replan if implementation drift changes architecture, public contracts, dependency direction, schema, auth, permission, payment, or design assumptions
 ```
 The project manager may use a prompt compiler or template system to build role commands, but the responsibility stays with the project manager. A role command is an auditable artifact: if a role agent fails because the command was vague, the harness should improve the command template rather than blaming the role agent alone.
@@ -648,16 +680,16 @@ If the current session was not started with the required role, stop and ask the
 This is not progressive adoption. The full harness exists by default; the role chain depends on task risk.
-All user-facing routes begin with `project-manager`. The project manager may hand off T0/T1 work to `coder` quickly, but it still owns translation, status reporting, and acceptance communication.
+All user-facing routes begin with `project-manager`. The project manager may hand off T0/T1 work to `coder` quickly, but it still owns status reporting and acceptance communication.
 | Task class | Examples | Required role route |
 | --- | --- | --- |
-| T0 trivial | copy, comments, docs typo, tiny config with no behavior change | `project-manager` -> `coder`; optional reviewer checklist |
-| T1 small scoped change | single-file bug, focused test addition, known-pattern fix | `project-manager` -> `coder` -> fresh review context or `reviewer` |
-| T2 ordinary feature | bounded behavior, normal multi-file feature, ordinary PR | `project-manager` -> `architect` -> `coder` -> `reviewer` |
-| T3 cross-module / architectural | cross-module change, module boundary change, refactor, new public surface | `project-manager` -> `architect` -> `coder` -> `reviewer` |
-| T4 high-risk | auth, permission, payment, billing, schema, data deletion, public API/SDK, security-sensitive infrastructure | `project-manager` -> `architect` -> relevant specialist if needed -> `coder` -> `reviewer` -> human approval |
-| T5 large rewrite / greenfield | new subsystem, major rewrite, migration across many modules | `project-manager` -> `architect`; then repeat `coder` -> `reviewer` per phase, with architect review at phase boundaries |
+| T0 trivial | copy, comments, docs typo, tiny config with no behavior change | `project-manager` -> `coder`; optional reviewer checklist; PM commit/PR |
+| T1 small scoped change | single-file bug, focused test addition, known-pattern fix | `project-manager` -> `coder` -> fresh review context or `reviewer` -> docs checklist; PM commit/PR |
+| T2 ordinary feature | bounded behavior, normal multi-file feature, ordinary PR | `project-manager` -> `architect` -> `coder` -> `reviewer` -> `architect` docs sync -> PM commit/PR |
+| T3 cross-module / architectural | cross-module change, module boundary change, refactor, new public surface | `project-manager` -> `architect` -> `coder` -> `reviewer` -> `architect` docs sync -> PM commit/PR |
+| T4 high-risk | auth, permission, payment, billing, schema, data deletion, public API/SDK, security-sensitive infrastructure | `project-manager` -> `architect` -> relevant specialist if needed -> `coder` -> `reviewer` -> `architect` docs sync -> human approval -> PM commit/PR |
+| T5 large rewrite / greenfield | new subsystem, major rewrite, migration across many modules | `project-manager` -> `architect`; then repeat `coder` -> `reviewer` -> `architect` docs sync per phase; PM commit/PR at phase or task boundary |
 If classification is unclear, use the stricter route.
@@ -682,9 +714,9 @@ Role responsibilities:
 ```text
 project-manager
-  owns user communication, multilingual translation, task clarification, task specs, role routing, and role command dispatch
-  translates user input into an English engineering task when needed
-  translates role outputs back into the user's preferred language
+  owns user communication, task clarification, task specs, role routing, and role command dispatch
+  turns user input into an engineering task when needed
+  summarizes role outputs back to the user
   creates and verifies handoff artifacts
   tracks progress, blockers, validation, docs sync, and Replan
   outputs task specs, role commands, status summaries, and final acceptance reports
@@ -693,7 +725,9 @@ project-manager
 architect
   owns architecture and plan
   defines module boundaries, file responsibilities, public contracts, dependency direction, risk, and phases
+  owns post-review docs sync and architecture drift checks before PM final acceptance
   outputs .ai/handoffs/<task-slug>/architecture-plan.md
+  outputs .ai/handoffs/<task-slug>/docs-sync-report.md when a post-review docs sync gate is required
   must not implement production code
 coder
@@ -705,13 +739,13 @@ coder
 reviewer
   owns independent acceptance and final test responsibility
-  checks scope, role compliance, architecture compliance, public contract compliance, docs sync, validation evidence, and risk
+  checks scope, role compliance, architecture compliance, public contract compliance, docs gaps, validation evidence, and risk
   checks, designs, and adds missing tests when needed
   may directly apply small, local, low-risk review fixes
   owns complex tests, E2E coverage, regression matrix, and release-level validation recommendations
   outputs .ai/handoffs/<task-slug>/review-report.md
   must escalate larger implementation issues to coder
-  must escalate architecture, public contract, or design issues to architect
+  must escalate architecture, public contract, design, or documentation drift issues to architect
 ```
 ### 7.5 Role Permission Matrix
@@ -720,8 +754,8 @@ Prompt rules are not enough. Role separation must be backed by tool scope, permi
 | Role | Suggested tools | Write scope | Must not |
 | --- | --- | --- | --- |
-| `project-manager` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | task specs, role commands, handoff metadata, status/progress/known-issues, final reports | implement non-trivial production code, approve without reviewer evidence, replace architect/coder/reviewer roles |
-| `architect` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | architecture plan, task spec, architecture docs only with approval | edit production code, rewrite tests, expand task scope |
+| `project-manager` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | task specs, role commands, handoff metadata, status/progress/known-issues, final reports, PR description | implement non-trivial production code, approve without reviewer/docs-sync evidence, replace architect/coder/reviewer roles |
+| `architect` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | architecture plan, docs sync report, task spec, approved architecture/module/testing/security docs | edit production code, rewrite tests, expand task scope |
 | `coder` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | approved source files, baseline tests, validation log, implementation log | change scope, public contracts, module boundaries, or test strategy without Replan |
 | `reviewer` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | review report, missing tests/fixtures, validation log, small review-scoped fixes | take over implementation, change architecture/public contracts, approve own implementation, weaken tests |
 | `security-specialist` | `Read`, `Grep`, `Glob`, `Bash`, `Edit`, `Write` | security review report and approved security tests | bypass approvals, edit production code without explicit scope |
@@ -731,8 +765,8 @@ Prompt rules are not enough. Role separation must be backed by tool scope, permi
 Recommended permission modes:
 ```text
-project-manager: default with write hooks limited to task specs, role commands, handoff metadata, state files, and final reports
-architect:  default with write hooks limited to architecture-plan.md, task specs, and approved docs
+project-manager: default with write hooks limited to task specs, role commands, handoff metadata, state files, final reports, and PR description
+architect:  default with write hooks limited to architecture-plan.md, docs-sync-report.md, task specs, and approved docs
 coder:      default or acceptEdits, but only inside approved scope
 reviewer:   default with production-code writes blocked except explicitly review-scoped small fixes; test writes allowed
 specialist: default with write hooks limited to specialist reports, tests, and approved files
@@ -749,13 +783,14 @@ Required handoff directory:
 ```text
 .ai/handoffs/<task-slug>/
   role-commands/
-    architect-command.md
-    coder-command.md
-    reviewer-command.md
+    architect.md
+    coder.md
+    reviewer.md
   architecture-plan.md
   implementation-log.md
   validation-log.md
   review-report.md
+  docs-sync-report.md
 ```
 Each role session must start by reading the artifacts it depends on:
@@ -769,6 +804,10 @@ architect
   reads: task request, task spec, ARCHITECTURE.md, MODULE_MAP.md, module-local CLAUDE.md, relevant source/tests
   writes: architecture-plan.md
+architect docs sync
+  reads: task spec, architecture-plan.md, implementation-log.md, validation-log.md, review-report.md, git diff, relevant docs
+  writes: docs updates when needed, docs-sync-report.md
 coder
   reads: task spec, architecture-plan.md, relevant module docs
   writes: code, baseline tests, implementation-log.md, validation-log.md
@@ -795,7 +834,7 @@ reviewer:
   owns complex test strategy, E2E smoke/release coverage, and regression matrix
   may directly apply small, local, low-risk review fixes
   must request coder fixes for larger implementation issues
-  must request architect review for architecture, public contract, dependency, schema, auth, permission, payment, or design issues
+  must request architect review for architecture, public contract, dependency, schema, auth, permission, payment, design, or docs drift issues
   must not weaken tests to pass validation
 ```
@@ -832,6 +871,7 @@ escalate to architect:
   public contract is wrong
   dependency direction is wrong
   schema, auth, permission, payment, public API, or security design is wrong
+  architecture, module, testing, security, or dependency docs are stale after implementation
   the implementation reveals that the architecture plan is invalid
 ```
@@ -896,9 +936,19 @@ Handoff artifact schemas:
 ## Escalations To Coder / Architect
 ## E2E / Regression Recommendation
 ## Validation Evidence
-## Docs Sync
+## Docs Gap Review
 ## Findings
 ## Decision
+# docs-sync-report.md
+## Summary
+## Architecture Drift Check
+## Docs Updated
+## Docs Reviewed And Left Unchanged
+## Public Contract / Module Boundary Notes
+## Remaining Documentation Risks
+## Decision
 ```
 ### 7.7 Role Session vs Subagent
@@ -909,8 +959,8 @@ Worktree isolation is by task, not by role:
 ```text
 one task
-  -> one branch
-  -> one worktree
+  -> one branch: feature/<task-slug>
+  -> one worktree: .ai/vcm/worktrees/<task-slug>
   -> one handoff directory
   -> architect -> coder -> reviewer in sequence
 ```
@@ -1068,7 +1118,7 @@ For large features:
 ```text
 project-manager session
-  -> communicate with user + translate intent + classify task + route roles + track process
+  -> communicate with user + clarify intent + classify task + route roles + track process
 architect session
   -> architecture-plan.md
@@ -1079,7 +1129,13 @@ coder session
 reviewer session
   -> review-report.md + missing tests/fixtures if needed + validation-log.md
-human approval
+architect docs-sync session
+  -> docs updates if needed + docs-sync-report.md
+human approval when required
+project-manager session
+  -> final acceptance + commit + PR submission
 ```
 For small bug fixes or ordinary PRs, one coder session is acceptable if the task spec is clear, file responsibilities are explicit, public contracts are defined when needed, and validation is cheap.
@@ -1382,8 +1438,8 @@ Default rule:
 ```text
 one task
-  -> one branch
-  -> one worktree
+  -> one branch: feature/<task-slug>
+  -> one worktree: .ai/vcm/worktrees/<task-slug>
   -> one handoff directory
   -> one PR
 ```
@@ -1423,9 +1479,19 @@ Branch rules:
 - never do AI implementation work directly on the main branch
 - one task branch should map to one task worktree
+- VCM-managed task branches should use `feature/<task-slug>`
+- VCM-managed task worktrees should live under `.ai/vcm/worktrees/<task-slug>`
+- `.gitignore` should contain a VCM managed block that ignores `.ai/vcm/`
+- a task should not switch to a different branch/worktree after creation; create a new task instead
 - large work should use phase commits on the same task branch unless phases are independently releasable
 - if a task becomes too large, split it into child tasks with explicit branch and PR ownership
+Cleanup rules:
+- after task completion, remove the task worktree only after role sessions are stopped and uncommitted work is handled
+- remove VCM task/session/message/orchestration metadata with the worktree cleanup
+- keep the task branch by default until PR merge; delete it only with explicit confirmation
 Small commits:
 - one commit per phase
@@ -1787,7 +1853,7 @@ behavior is correct
 ## Role / Handoff
-- [ ] The task used an explicit `project-manager` role session for user communication, translation, routing, and status reporting.
+- [ ] The task used an explicit `project-manager` role session for user communication, routing, and status reporting.
 - [ ] Task severity was classified.
 - [ ] Required role route was followed or an exception was approved.
 - [ ] The project manager verified required handoff artifacts, validation evidence, docs sync, and remaining risks.
@@ -1799,6 +1865,9 @@ behavior is correct
 - [ ] Any reviewer direct fixes were small, local, low-risk, and review-scoped.
 - [ ] Larger implementation issues were returned to coder.
 - [ ] Architecture, public contract, dependency, schema, auth, permission, payment, or design issues were returned to architect.
+- [ ] For T2+ work, architect performed post-review docs sync / architecture drift check before final PM acceptance.
+- [ ] Docs updates or a docs-sync-report explain why affected architecture/module/testing/security/dependency docs are current.
+- [ ] The project manager prepared final acceptance, commit, and PR only after reviewer and docs-sync gates passed or an exception was approved.
 - [ ] Task-level validation evidence is recorded in `.ai/handoffs/<task-slug>/validation-log.md` when a handoff directory exists.
 ## Architecture
@@ -2079,7 +2148,7 @@ Monthly review:
 If you can only enforce 16 rules, enforce these:
 1. User-facing tasks start with `claude --agent project-manager`; untagged sessions are not implicit project managers.
-2. The `project-manager` agent owns user communication, translation, task clarification, and precise role command dispatch.
+2. The `project-manager` agent owns user communication, task clarification, and precise role command dispatch.
 3. Complex tasks use explicit role sessions, handoff artifacts, and plan first; do not edit directly.
 4. One task uses one branch, one worktree, one handoff directory, and one PR by default.
 5. Role sessions for the same task work in the same task worktree sequentially; parallel write work uses separate task or sub-task worktrees.
@@ -2123,7 +2192,7 @@ Project manager becomes coder/reviewer
   -> project manager coordinates and verifies; role sessions execute
 Project manager only tracks status but sends vague role prompts
-  -> project manager translates user intent into precise role commands with scope, contracts, validation, outputs, and stop conditions
+  -> project manager turns user intent into precise role commands with scope, contracts, validation, outputs, and stop conditions
 Role-based worktree fragmentation
   -> one task worktree; architect -> coder -> reviewer hand off sequentially inside it