crewbee 0.1.10 → 0.1.12

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 (156) hide show
  1. package/README.md +438 -239
  2. package/README.zh-CN.md +320 -129
  3. package/dist/opencode-plugin.mjs +765 -506
  4. package/dist/src/adapters/opencode/bootstrap.d.ts +1 -0
  5. package/dist/src/adapters/opencode/bootstrap.d.ts.map +1 -1
  6. package/dist/src/adapters/opencode/bootstrap.js +1 -0
  7. package/dist/src/adapters/opencode/bootstrap.js.map +1 -1
  8. package/dist/src/adapters/opencode/chat-message-hook.d.ts.map +1 -1
  9. package/dist/src/adapters/opencode/chat-message-hook.js +2 -1
  10. package/dist/src/adapters/opencode/chat-message-hook.js.map +1 -1
  11. package/dist/src/adapters/opencode/config-hook.d.ts.map +1 -1
  12. package/dist/src/adapters/opencode/config-hook.js +3 -3
  13. package/dist/src/adapters/opencode/config-hook.js.map +1 -1
  14. package/dist/src/adapters/opencode/defaults.d.ts +3 -0
  15. package/dist/src/adapters/opencode/defaults.d.ts.map +1 -0
  16. package/dist/src/adapters/opencode/defaults.js +5 -0
  17. package/dist/src/adapters/opencode/defaults.js.map +1 -0
  18. package/dist/src/adapters/opencode/index.d.ts +1 -0
  19. package/dist/src/adapters/opencode/index.d.ts.map +1 -1
  20. package/dist/src/adapters/opencode/index.js +3 -1
  21. package/dist/src/adapters/opencode/index.js.map +1 -1
  22. package/dist/src/adapters/opencode/model-resolution.d.ts +33 -0
  23. package/dist/src/adapters/opencode/model-resolution.d.ts.map +1 -0
  24. package/dist/src/adapters/opencode/model-resolution.js +180 -0
  25. package/dist/src/adapters/opencode/model-resolution.js.map +1 -0
  26. package/dist/src/adapters/opencode/projection.d.ts +4 -1
  27. package/dist/src/adapters/opencode/projection.d.ts.map +1 -1
  28. package/dist/src/adapters/opencode/projection.js +7 -12
  29. package/dist/src/adapters/opencode/projection.js.map +1 -1
  30. package/dist/src/adapters/opencode/prompt-builder.d.ts.map +1 -1
  31. package/dist/src/adapters/opencode/prompt-builder.js +7 -17
  32. package/dist/src/adapters/opencode/prompt-builder.js.map +1 -1
  33. package/dist/src/agent-teams/canonical-agent-id.d.ts.map +1 -1
  34. package/dist/src/agent-teams/canonical-agent-id.js +11 -0
  35. package/dist/src/agent-teams/canonical-agent-id.js.map +1 -1
  36. package/dist/src/agent-teams/constants.d.ts +4 -0
  37. package/dist/src/agent-teams/constants.d.ts.map +1 -1
  38. package/dist/src/agent-teams/constants.js +14 -1
  39. package/dist/src/agent-teams/constants.js.map +1 -1
  40. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts +1 -3
  41. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts.map +1 -1
  42. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js +4 -14
  43. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js.map +1 -1
  44. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts +4 -0
  45. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts.map +1 -0
  46. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js +17 -0
  47. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js.map +1 -0
  48. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js +5 -5
  49. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js.map +1 -1
  50. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js +4 -4
  51. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js.map +1 -1
  52. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js +8 -8
  53. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js.map +1 -1
  54. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js +8 -8
  55. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js.map +1 -1
  56. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js +2 -2
  57. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js.map +1 -1
  58. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js +5 -5
  59. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js.map +1 -1
  60. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js +6 -6
  61. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js.map +1 -1
  62. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js +5 -5
  63. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js.map +1 -1
  64. package/dist/src/agent-teams/embedded/coding-team.d.ts.map +1 -1
  65. package/dist/src/agent-teams/embedded/coding-team.js +20 -10
  66. package/dist/src/agent-teams/embedded/coding-team.js.map +1 -1
  67. package/dist/src/agent-teams/filesystem.d.ts +10 -0
  68. package/dist/src/agent-teams/filesystem.d.ts.map +1 -1
  69. package/dist/src/agent-teams/filesystem.js +32 -0
  70. package/dist/src/agent-teams/filesystem.js.map +1 -1
  71. package/dist/src/agent-teams/library.d.ts.map +1 -1
  72. package/dist/src/agent-teams/library.js +7 -2
  73. package/dist/src/agent-teams/library.js.map +1 -1
  74. package/dist/src/agent-teams/parsers.d.ts.map +1 -1
  75. package/dist/src/agent-teams/parsers.js +7 -1
  76. package/dist/src/agent-teams/parsers.js.map +1 -1
  77. package/dist/src/agent-teams/validation.d.ts.map +1 -1
  78. package/dist/src/agent-teams/validation.js +14 -0
  79. package/dist/src/agent-teams/validation.js.map +1 -1
  80. package/dist/src/cli/doctor.d.ts.map +1 -1
  81. package/dist/src/cli/doctor.js +31 -7
  82. package/dist/src/cli/doctor.js.map +1 -1
  83. package/dist/src/cli/install.d.ts.map +1 -1
  84. package/dist/src/cli/install.js +8 -3
  85. package/dist/src/cli/install.js.map +1 -1
  86. package/dist/src/cli/parse-install-options.d.ts.map +1 -1
  87. package/dist/src/cli/parse-install-options.js +31 -0
  88. package/dist/src/cli/parse-install-options.js.map +1 -1
  89. package/dist/src/cli/parse-setup-options.d.ts +3 -0
  90. package/dist/src/cli/parse-setup-options.d.ts.map +1 -0
  91. package/dist/src/cli/parse-setup-options.js +102 -0
  92. package/dist/src/cli/parse-setup-options.js.map +1 -0
  93. package/dist/src/cli/render-help.d.ts.map +1 -1
  94. package/dist/src/cli/render-help.js +10 -3
  95. package/dist/src/cli/render-help.js.map +1 -1
  96. package/dist/src/cli/run-cli.d.ts.map +1 -1
  97. package/dist/src/cli/run-cli.js +20 -1
  98. package/dist/src/cli/run-cli.js.map +1 -1
  99. package/dist/src/cli/setup.d.ts +7 -0
  100. package/dist/src/cli/setup.d.ts.map +1 -0
  101. package/dist/src/cli/setup.js +70 -0
  102. package/dist/src/cli/setup.js.map +1 -0
  103. package/dist/src/cli/uninstall-user.d.ts.map +1 -1
  104. package/dist/src/cli/uninstall-user.js +2 -1
  105. package/dist/src/cli/uninstall-user.js.map +1 -1
  106. package/dist/src/core/index.d.ts +13 -1
  107. package/dist/src/core/index.d.ts.map +1 -1
  108. package/dist/src/install/config-writer.d.ts +2 -18
  109. package/dist/src/install/config-writer.d.ts.map +1 -1
  110. package/dist/src/install/config-writer.js +9 -94
  111. package/dist/src/install/config-writer.js.map +1 -1
  112. package/dist/src/install/doctor.d.ts.map +1 -1
  113. package/dist/src/install/doctor.js +21 -19
  114. package/dist/src/install/doctor.js.map +1 -1
  115. package/dist/src/install/index.d.ts +6 -4
  116. package/dist/src/install/index.d.ts.map +1 -1
  117. package/dist/src/install/index.js +20 -11
  118. package/dist/src/install/index.js.map +1 -1
  119. package/dist/src/install/install.d.ts.map +1 -1
  120. package/dist/src/install/install.js +50 -33
  121. package/dist/src/install/install.js.map +1 -1
  122. package/dist/src/install/opencode-cli.d.ts +14 -0
  123. package/dist/src/install/opencode-cli.d.ts.map +1 -0
  124. package/dist/src/install/opencode-cli.js +58 -0
  125. package/dist/src/install/opencode-cli.js.map +1 -0
  126. package/dist/src/install/opencode-config-file.d.ts +26 -0
  127. package/dist/src/install/opencode-config-file.d.ts.map +1 -0
  128. package/dist/src/install/opencode-config-file.js +131 -0
  129. package/dist/src/install/opencode-config-file.js.map +1 -0
  130. package/dist/src/install/package-installation.d.ts +19 -0
  131. package/dist/src/install/package-installation.d.ts.map +1 -0
  132. package/dist/src/install/package-installation.js +95 -0
  133. package/dist/src/install/package-installation.js.map +1 -0
  134. package/dist/src/install/package-manager.d.ts +1 -14
  135. package/dist/src/install/package-manager.d.ts.map +1 -1
  136. package/dist/src/install/package-manager.js +8 -79
  137. package/dist/src/install/package-manager.js.map +1 -1
  138. package/dist/src/install/plugin-entry.d.ts +3 -1
  139. package/dist/src/install/plugin-entry.d.ts.map +1 -1
  140. package/dist/src/install/plugin-entry.js +11 -22
  141. package/dist/src/install/plugin-entry.js.map +1 -1
  142. package/dist/src/install/setup.d.ts +6 -0
  143. package/dist/src/install/setup.d.ts.map +1 -0
  144. package/dist/src/install/setup.js +72 -0
  145. package/dist/src/install/setup.js.map +1 -0
  146. package/dist/src/install/types.d.ts +36 -0
  147. package/dist/src/install/types.d.ts.map +1 -1
  148. package/dist/src/install/uninstall.d.ts.map +1 -1
  149. package/dist/src/install/uninstall.js +30 -18
  150. package/dist/src/install/uninstall.js.map +1 -1
  151. package/dist/src/render/prompt-document-renderer.d.ts +4 -0
  152. package/dist/src/render/prompt-document-renderer.d.ts.map +1 -0
  153. package/dist/src/render/prompt-document-renderer.js +19 -0
  154. package/dist/src/render/prompt-document-renderer.js.map +1 -0
  155. package/package.json +5 -2
  156. package/templates/crewbee.json +30 -1
package/README.md CHANGED
@@ -6,69 +6,79 @@
6
6
  <img src="assets/crewbee-intro.png" alt="Turn scattered agents into real teams" width="100%" />
7
7
  </p>
8
8
 
9
- <p align="center"><strong>Team-first agent engineering for real host runtimes.</strong></p>
9
+ <p align="center"><strong>An Agent Team framework for OpenCode.</strong></p>
10
10
 
11
- CrewBee is a **Team-first** Agent Team framework.
11
+ CrewBee lets you design different **Agent Teams** for different tasks or projects, and switch flexibly between **single-agent execution** and **multi-agent collaboration** based on task complexity.
12
12
 
13
- It provides a Team-oriented way to define, project, and adapt agent systems to host runtimes, turning scattered prompts, rules, and collaboration conventions into maintainable, portable, and runnable Team assets.
13
+ It is not a prompt pack or a forced multi-agent ritual. CrewBee turns agent roles, collaboration patterns, context management, review flow, completion criteria, and host adaptation into maintainable, runnable, and reusable Team engineering assets.
14
14
 
15
- **Current focus:** make Team-based agent systems portable, composable, and actually runnable inside OpenCode.
15
+ **Current focus:** make Team-level agent systems clearly definable, projectable across host runtimes, and runnable inside OpenCode.
16
+
17
+ ---
16
18
 
17
19
  ## Why CrewBee
18
20
 
19
- - **Team-first, not prompt-first** — model leaders, members, workflow, and policy as durable engineering assets.
20
- - **Host-agnostic core** — keep Team definitions independent from any single runtime.
21
- - **Projection-based runtime model** — map one Team definition into a concrete host safely and repeatably.
22
- - **OpenCode-ready today** — includes the full plugin, agent projection, install, doctor, and release path.
21
+ * **Design different Agent Teams for different tasks or projects** — Different work can have different roles, rules, workflows, and completion criteria.
22
+ * **Switch between single-agent and multi-agent collaboration based on task complexity** — Keep simple tasks fast and lightweight; use Team collaboration, support agents, review, and verification for complex tasks.
23
+ * **Keep the main agent as the owner of the most complete context** — The main agent holds the user goal, project constraints, support findings, review feedback, and verification results, so key decisions are based on fuller evidence.
24
+ * **Use context-isolated delegation** — Support agents work in dedicated contexts for exploration, research, and review, then return high-signal findings to the main agent. This reduces the main agent’s context and attention load.
25
+ * **Built-in mature Coding Team** — CrewBee includes a Coding Team with clear role responsibilities, review flow, and completion criteria for development, debugging, refactoring, and verification work.
26
+ * **Project Context direction across sessions** — Next, CrewBee will strengthen automatically maintained project context, so long-running projects can keep summaries of project positioning, framework design, history, current state, and plans across sessions.
27
+ * **Copyable, modifiable, and contributable Team templates** — Teams are engineering assets that can be refined, versioned, and shared.
23
28
 
24
- The current version already delivers a complete **CrewBee → OpenCode** MVP path:
29
+ CrewBee has already completed the **CrewBee → OpenCode** MVP path:
25
30
 
26
- * host-agnostic Team / Agent definitions
31
+ * Host-agnostic Team / Agent definitions
27
32
  * Team Library assembly and validation
28
- * Runtime Projection with formal leader default entry selection
29
- * OpenCode agent projection, aliases, config patching, and session binding
33
+ * Runtime Projection and formal leader default selection
34
+ * OpenCode agent config projection, aliases, config patches, and session binding
30
35
  * OpenCode plugin entry, delegation tools, event wiring, and system prompt injection
31
- * local build, user-level install, doctor checks, and uninstall flow
36
+ * Local build, user-level installation, doctor checks, and uninstall flow
32
37
 
33
- > In short:
38
+ > Simple mental model:
34
39
  >
35
- > **CrewBee = Agent Team definition framework + Runtime Projection layer + host adapter layer (currently OpenCode)**
40
+ > **CrewBee = Agent Team definition framework + Runtime Projection layer + Host adapter layer, currently for OpenCode**
41
+
42
+ ---
36
43
 
37
44
  ## Quick Links
38
45
 
39
- - [CrewBeeLab Website](https://crewbeelab.github.io)
40
- - [Installation Guide](docs/guide/installation.md)
41
- - [Custom Agent Team Guide](docs/guide/custom-agent-team.en.md)
42
- - [Project-Level Team Configuration Guide](docs/guide/project-team-config.en.md)
43
- - [Release Guide](docs/guide/release.md)
46
+ * [CrewBeeLab Website](https://crewbeelab.github.io)
47
+ * [Installation Guide](docs/guide/installation.md)
48
+ * [Custom Agent Team Guide](docs/guide/custom-agent-team.en.md)
49
+ * [Project-level Team Configuration Guide](docs/guide/project-team-config.en.md)
50
+ * [Release Guide](docs/guide/release.md)
51
+
52
+ For Chinese documentation, start from [README.zh-CN.md](README.zh-CN.md) and the Chinese guide files under `docs/guide`.
44
53
 
45
- For Chinese documentation, use [README.zh-CN.md](README.zh-CN.md) and the `*.zh-CN.md` / default Chinese guide files under `docs/guide`.
54
+ ---
46
55
 
47
56
  ## Agent IDs in OpenCode
48
57
 
49
- CrewBee uses a single **canonical agent id** across projection, default selection, session binding, delegation, and user-facing selection.
58
+ CrewBee uses a single **canonical agent id** across projection, default selection, session binding, delegation, and user-visible names.
50
59
 
51
60
  Examples:
52
61
 
53
- - `coding-leader`
54
- - `coding-executor`
55
- - `coding-reviewer`
62
+ * `coding-leader`
63
+ * `coding-executor`
64
+ * `coding-reviewer`
56
65
 
57
- The same id is used for OpenCode `default_agent`, session-level selection, delegation targets, and projected runtime/config ids shown to users.
66
+ The same id is used for OpenCode `default_agent`, explicitly selected agents in a session, delegation targets, and user-visible runtime / config ids.
58
67
 
59
68
  ---
60
69
 
61
70
  ## Table of Contents
62
71
 
63
72
  * [What CrewBee Is](#what-crewbee-is)
64
- * [What Problems CrewBee Solves](#what-problems-crewbee-solves)
73
+ * [What CrewBee Solves](#what-crewbee-solves)
65
74
  * [Core Features](#core-features)
66
75
  * [Installation](#installation)
67
76
  * [Quick Start](#quick-start)
68
- * [How Agent Teams and Agent Profiles Are Defined](#how-agent-teams-and-agent-profiles-are-defined)
77
+ * [Agent Team and Agent Profile Definitions](#agent-team-and-agent-profile-definitions)
69
78
  * [How the OpenCode Runtime Works](#how-the-opencode-runtime-works)
70
79
  * [Built-in Coding Team Design](#built-in-coding-team-design)
71
- * [Configuration, Install, and Operations Scripts](#configuration-install-and-operations-scripts)
80
+ * [Next: Project Context](#next-project-context)
81
+ * [Configuration, Installation, and Operations Scripts](#configuration-installation-and-operations-scripts)
72
82
  * [Uninstall](#uninstall)
73
83
  * [Acknowledgements](#acknowledgements)
74
84
 
@@ -76,81 +86,256 @@ The same id is used for OpenCode `default_agent`, session-level selection, deleg
76
86
 
77
87
  ## What CrewBee Is
78
88
 
79
- In CrewBee, the real first-class object is not a single Agent, but a **Team**.
80
- A Team is not just a collection of prompts; it is a structured definition unit that includes at least:
89
+ CrewBee is an Agent Team framework for real host runtimes.
90
+
91
+ In CrewBee, the first-class object is not a single Agent, but a **Team**. A Team is not a concatenation of prompt fragments. It is a structured definition unit that includes at least:
81
92
 
82
93
  * Team identity and positioning
83
94
  * formal leader
84
95
  * members
85
96
  * workflow
86
- * Team shared rules
97
+ * Team-level shared rules
87
98
  * Agent Profiles
88
99
  * Prompt Projection
89
100
  * host runtime mapping
90
101
 
91
- CrewBee does not currently try to auto-select a Team for you, nor does it try to auto-decide the right organizational structure for every task.
92
- At the current stage, the basic usage model is:
102
+ CrewBee aims to turn scattered agent prompts, rules, and collaboration conventions into maintainable, portable, and runnable Team assets.
93
103
 
94
- * the user selects a Team entry Agent in the host
95
- * CrewBee projects the Team definition into the host runtime
96
- * runtime semantics are maintained through session binding, delegation, and system prompt injection
104
+ The current usage model is:
105
+
106
+ * The user selects a Team entry agent in the host runtime.
107
+ * CrewBee projects the Team definition into the host runtime in a stable way.
108
+ * At runtime, CrewBee preserves Team semantics through session binding, delegation, and system prompt injection.
109
+
110
+ CrewBee does not currently force automatic Team selection or automatically decide the organization structure for every task. It first focuses on making Team definitions, Team projection, runtime binding, and OpenCode adaptation solid.
97
111
 
98
112
  ---
99
113
 
100
- ## What Problems CrewBee Solves
114
+ ## What CrewBee Solves
115
+
116
+ CrewBee mainly solves seven problems.
117
+
118
+ ### 1. Design different Agent Teams for different tasks or projects
119
+
120
+ Coding, research, writing, analysis, marketing, and long-running project maintenance are not the same kind of work. They need different role structures, working rules, tool boundaries, review flows, and completion criteria.
121
+
122
+ CrewBee lets you design different Agent Teams for different tasks or projects instead of using one increasingly long general-purpose prompt for everything.
123
+
124
+ ### 2. Switch flexibly between single-agent and multi-agent collaboration based on task complexity
125
+
126
+ Simple tasks need fast responses, fewer tokens, and fewer steps. Complex tasks need support agents, independent review, verification, and clearer completion gates.
101
127
 
102
- CrewBee primarily solves three kinds of problems:
128
+ CrewBee is not designed to turn every task into multi-agent collaboration by default. It is designed to choose the right execution mode based on task complexity.
103
129
 
104
- ### 1. Turning scattered Agent practices into maintainable Team assets
130
+ ### 3. Keep the main agent as the owner of the most complete context
105
131
 
106
- Many Agent workflows still live in prompts, host configs, and informal conventions. That makes them hard to reuse, migrate, and maintain over time. CrewBee turns them into stable Team definitions.
132
+ In complex tasks, codebase exploration, external research, review, and verification may all produce important information.
107
133
 
108
- ### 2. Using different Teams for different task types instead of one prompt for everything
134
+ CrewBee keeps the main agent / formal leader as the owner of the most complete task context. The main agent collects the user goal, project constraints, support findings, review feedback, and verification results before making key decisions and closing the task.
109
135
 
110
- Coding, research, writing, analysis, and operational work do not share the same optimal working style. CrewBee’s core idea is to define different Teams for different scenarios instead of reusing one generic prompt stack everywhere.
136
+ ### 4. Reduce the main agent’s context and attention load through context-isolated delegation
111
137
 
112
- ### 3. Making execution style selectable and manageable
138
+ Complex work should not dump every search trace, side exploration, failed path, and low-signal detail into the main agent’s context.
113
139
 
114
- Many systems focus on whether agents can execute. CrewBee puts more emphasis on how they should execute: which entry point to use, when to involve support agents, and how to keep the execution path understandable and controllable.
140
+ CrewBee uses delegation so support agents can work in dedicated contexts for codebase exploration, research, review, or multimodal interpretation, then return high-signal findings to the main agent. This reduces main-context pollution and the main agent’s attention load.
141
+
142
+ ### 5. Built-in mature Coding Team with review flow and completion criteria
143
+
144
+ Coding tasks need more than code generation. They need codebase exploration, external research, independent review, verification evidence, and completion criteria.
145
+
146
+ CrewBee’s built-in Coding Team uses direct responsibility-based role names and emphasizes review and completion criteria, helping complex coding tasks reach a more reliable closure.
147
+
148
+ ### 6. Project Context direction across sessions
149
+
150
+ Long-running projects should not require the user to re-explain project positioning, framework design, history, current state, and next steps every time a new session starts.
151
+
152
+ CrewBee’s next stage will strengthen automatically maintained Project Context, so agents can use project summaries to read code heuristically and reduce the context cost of repeatedly scanning the whole codebase.
153
+
154
+ ### 7. Copyable, modifiable, and contributable Team templates
155
+
156
+ A Team is not just internal configuration. It is an engineering asset that can be copied, modified, versioned, and contributed.
157
+
158
+ This lets users start from built-in Teams or templates, then gradually build their own agent workflows.
115
159
 
116
160
  ---
117
161
 
118
162
  ## Core Features
119
163
 
120
- ### 1. Team-first static model
164
+ ### 1. Design different Agent Teams for different tasks or projects
165
+
166
+ CrewBee treats Team as a first-class object rather than focusing only on scattered agent prompts.
167
+
168
+ A Team can have its own:
169
+
170
+ * task positioning
171
+ * default entry agent
172
+ * member responsibilities
173
+ * workflow
174
+ * shared rules
175
+ * tool boundaries
176
+ * review flow
177
+ * completion criteria
178
+ * output style
179
+
180
+ This means you can design different Teams for different tasks or projects, such as:
181
+
182
+ * `CodingTeam`: development, fixing, debugging, refactoring, verification
183
+ * `GeneralTeam`: research, analysis, writing, planning
184
+ * `ResearchOpsTeam`: evidence retrieval, material organization, conclusion synthesis
185
+ * `MarketingOpsTeam`: open-source release, promotion, community feedback
186
+ * `ProjectContextTeam`: project context maintenance, state updates, cross-session handoff
187
+ * `WukongTeam`: high-uncertainty exploration and long-running complex tasks
188
+
189
+ ### 2. Switch between single-agent and multi-agent collaboration based on task complexity
190
+
191
+ CrewBee does not make multi-agent collaboration a default ritual. It supports choosing different execution modes based on task complexity.
192
+
193
+ **Single-agent execution** fits:
194
+
195
+ * simple questions
196
+ * small code changes
197
+ * local explanations
198
+ * quick summarization
199
+ * low-risk tasks
200
+ * tasks with clear context and clear goals
201
+
202
+ **Multi-agent collaboration** fits:
203
+
204
+ * cross-file implementation
205
+ * complex bug fixes
206
+ * external research
207
+ * architecture decisions
208
+ * independent review
209
+ * tasks requiring verification evidence
210
+ * long-running project work
211
+
212
+ Simple tasks stay fast. Complex tasks use Team collaboration.
213
+
214
+ ### 3. Main agent owns the most complete context for fuller decisions
215
+
216
+ CrewBee Teams use the main agent / formal leader as the task entry point, mainline owner, and final closer.
217
+
218
+ The main agent holds the most complete task context, including:
219
+
220
+ * user goal
221
+ * project constraints
222
+ * current task state
223
+ * findings returned by support agents
224
+ * review feedback
225
+ * verification results
226
+ * risks and unresolved items
227
+
228
+ Key decisions are made by the main agent based on this combined context, instead of being made globally by support agents that only hold partial information.
229
+
230
+ ### 4. Context-isolated delegation reduces the main agent’s context and attention load
231
+
232
+ CrewBee’s support collaboration emphasizes context-isolated delegation:
233
+
234
+ ```text
235
+ The main agent owns the main task context.
236
+ Support agents work on specialized tasks in dedicated contexts.
237
+ Support agents return high-signal findings to the main agent.
238
+ The main agent continues decision-making and final closure based on those findings.
239
+ ```
240
+
241
+ Support tasks include:
242
+
243
+ * codebase exploration
244
+ * external documentation research
245
+ * evidence organization
246
+ * multimodal interpretation
247
+ * independent review
248
+ * high-level architecture advice
249
+
250
+ This prevents side searches, failed paths, low-signal material, and review traces from polluting the main context.
251
+
252
+ ### 5. Built-in mature Coding Team with review flow and completion criteria
253
+
254
+ CrewBee’s most important methodology sample today is the built-in Coding Team.
255
+
256
+ It is not a single Coder Agent, but an Agent Team designed for software engineering work. The recommended structure includes:
257
+
258
+ ```text
259
+ coding-leader
260
+ coding-executor
261
+ codebase-explorer
262
+ web-researcher
263
+ reviewer
264
+ principal-advisor
265
+ multimodal-looker
266
+ task-orchestrator
267
+ ```
268
+
269
+ The built-in Coding Team uses direct responsibility-based role names so users can quickly understand what each agent does.
270
+
271
+ | Built-in Coding Team Role | Responsibility |
272
+ | ------------------------- | --------------------------------------------------------------------------------------------------- |
273
+ | `coding-leader` | Default entry point, task owner, and final closer |
274
+ | `coding-executor` | Implements clear development, fixing, debugging, and local refactoring tasks |
275
+ | `codebase-explorer` | Locates code entry points, call chains, similar implementations, and historical clues |
276
+ | `web-researcher` | Researches official docs, external references, open-source implementations, and version differences |
277
+ | `reviewer` | Independently reviews risks, omissions, verification evidence, and completion criteria |
278
+ | `principal-advisor` | Provides high-level advice on architecture, performance, and complexity decisions |
279
+ | `multimodal-looker` | Interprets screenshots, charts, PDFs, UI images, and visual materials |
280
+ | `task-orchestrator` | Handles large plans, multi-wave tasks, and unified QA orchestration |
281
+
282
+ Completion in the Coding Team should not depend only on “the agent thinks it is done.” It should include explicit completion criteria whenever possible, such as:
283
+
284
+ ```text
285
+ - The target issue has been located.
286
+ - The change has a clear rationale.
287
+ - The required implementation or fix has been completed.
288
+ - Available diagnostics / build / tests have been run.
289
+ - The reviewer found no real blocking issue.
290
+ - Unverified items and residual risks have been stated.
291
+ ```
292
+
293
+ ### 6. Host-agnostic definitions and OpenCode Runtime Projection
121
294
 
122
- CrewBee treats Teams as first-class objects rather than isolated agent prompts.
123
- That means:
295
+ CrewBee first converts the Team-first structure into a unified intermediate representation, then maps it into concrete host runtimes.
124
296
 
125
- * Teams have a formal leader
126
- * Teams have policy
127
- * Teams have members and workflow
128
- * Teams have a host-agnostic structural model
297
+ The current primary host is OpenCode.
129
298
 
130
- ### 2. Host-agnostic Runtime Projection
299
+ The current OpenCode MVP path includes:
131
300
 
132
- CrewBee first converts Team-first structures into a unified intermediate model, then maps that model into specific hosts.
133
- This keeps Team / Agent definitions as host-agnostic as possible and makes long-term maintenance and future expansion easier.
301
+ * Team Library loading
302
+ * Team / Agent validation
303
+ * Runtime Projection
304
+ * formal leader default selection
305
+ * projected agent generation
306
+ * OpenCode config patch
307
+ * session binding
308
+ * delegation tooling
309
+ * plugin entry
310
+ * user-level install
311
+ * doctor verification
134
312
 
135
- ### 3. OpenCode adapter and plugin runtime
313
+ This makes CrewBee more than a prompt folder. It is a runtime framework that can actually plug into OpenCode.
136
314
 
137
- CrewBee already supports the full path from Team / Agent definitions to runnable OpenCode agents, including:
315
+ ### 7. Copyable, modifiable, and contributable Team templates
138
316
 
139
- * projected agent → OpenCode agent config
140
- * Team / Agent prompt construction
141
- * config patch generation
142
- * host event integration
143
- * delegation tool wiring
317
+ CrewBee Teams are file-based engineering assets that can be copied, modified, versioned, and contributed.
144
318
 
145
- ### 4. Prompts stay low-coupling while preserving execution semantics
319
+ Users can:
146
320
 
147
- CrewBee does not fall back to “one renderer per field”, nor does it dump every top-level block transparently.
321
+ * use built-in Teams
322
+ * copy Team templates
323
+ * modify role structures
324
+ * adjust shared rules
325
+ * encode their own workflow
326
+ * contribute Teams back to the community
148
327
 
149
- Instead, it uses:
328
+ Many users may not modify CrewBee core, but they can still start from a template and build their own Team.
150
329
 
151
- > **a small shared semantic skeleton + general structural handling + structured rendering**
330
+ ### 8. Prompts are decoupled while preserving execution semantics
152
331
 
153
- For example, the Agent prompt skeleton is organized around execution thinking:
332
+ CrewBee does not fall back to an old pattern where every field needs a dedicated schema and renderer. It also does not simply dump every top-level block into the prompt.
333
+
334
+ The current approach is:
335
+
336
+ > **a small set of shared semantic sections + generic structural processing + structured rendering**
337
+
338
+ For example, the Agent prompt skeleton is organized around execution cognition:
154
339
 
155
340
  * Persona Core
156
341
  * Responsibility Core
@@ -176,147 +361,105 @@ This helps the model quickly establish:
176
361
 
177
362
  * who I am
178
363
  * what I am responsible for
179
- * how I normally act
364
+ * how I act by default
180
365
  * when to delegate / review / ask / stop
181
- * what counts as done
366
+ * what counts as completion
182
367
  * how to recover from failure
183
368
 
184
- ### 5. Collaboration produces directly usable delegation targets
369
+ ### 9. Collaboration generates runtime-usable delegation targets
185
370
 
186
- Generated `Collaboration` output is not just a plain list of profile bindings. It combines:
371
+ The generated `Collaboration` section is not just a simple list of collaboration bindings from the profile. It combines:
187
372
 
188
- * collaboration targets declared in Agent Profiles
373
+ * subagent collaboration declarations from the Agent Profile
189
374
  * `members` descriptions from the Team Manifest
190
375
  * projected ids that OpenCode can resolve
191
376
 
192
- This lets the runtime surface delegation-ready agent entries.
377
+ Then it generates:
378
+
379
+ * `Id`
380
+ * `Description`
381
+ * `When To Delegate`
193
382
 
194
- ### 6. Team Contract is compressed into an executable handbook
383
+ This makes delegation targets directly usable at runtime.
195
384
 
196
- Instead of mechanically rendering the whole governance block, CrewBee compresses Team prompt output into:
385
+ ### 10. Team Contract is compressed into an executable handbook
386
+
387
+ The Team prompt does not mechanically render the entire governance config. It is compressed into:
197
388
 
198
389
  * `Working Rules`
199
390
  * `Approval & Safety`
200
391
 
201
- This makes Team contracts much easier for models to consume.
392
+ This makes the Team contract easier for the model to consume and avoids mechanical expansion of governance fields.
202
393
 
203
- ### 7. User-level install and operations flow
394
+ ### 11. User-level installation and operations flow
204
395
 
205
- CrewBee already includes a complete local build, user-level install, doctor, and uninstall flow, so it can be used as a stable OpenCode user-level plugin.
396
+ CrewBee already has a complete local build, user-level installation, doctor verification, and uninstall flow, so it can be installed as a user-level OpenCode plugin.
206
397
 
207
398
  ---
208
399
 
209
400
  ## Installation
210
401
 
211
- ### Shortest path for humans
212
-
213
- If you are using an LLM Agent, just send it this:
214
-
215
- ```text
216
- Please install CrewBee by following docs/guide/installation.md.
217
- Use the OpenCode user-level installation flow only, not the old project-local flow.
218
- ```
219
-
220
- Or read the guide yourself:
221
-
222
- * [Installation Guide](docs/guide/installation.md)
223
-
224
- ### Shortest path for LLM Agents
225
-
226
- Read and follow the English guides:
227
-
228
- ```text
229
- docs/guide/installation.md
230
- docs/guide/release.md
231
- ```
232
-
233
- ### One-click local install script for Windows
234
-
235
- The repository already provides:
236
-
237
- ```bat
238
- scripts\install-local-user.bat
239
- ```
240
-
241
- It runs:
242
-
243
- 1. `npm install`
244
- 2. `npm run install:local:user`
245
- 3. `npm run doctor`
246
-
247
- ---
248
-
249
- ## Quick Start
250
-
251
- ### Development build
402
+ Install CrewBee for OpenCode in one command:
252
403
 
253
404
  ```bash
254
- npm install
255
- npm run typecheck
256
- npm run build
405
+ npx crewbee@latest setup --with-opencode
257
406
  ```
258
407
 
259
- ### Local user-level install
260
-
261
- Recommended from the repository root:
408
+ If you already have OpenCode:
262
409
 
263
410
  ```bash
264
- npm install
265
- npm run install:local:user
411
+ npx crewbee@latest setup
266
412
  ```
267
413
 
268
- This does four things:
414
+ CrewBee installs into the OpenCode user-level workspace, writes the canonical plugin entry `"crewbee"`, runs doctor checks, and does not modify your repository files.
269
415
 
270
- 1. builds CrewBee
271
- 2. packs a stable local tarball to `.artifacts/local/crewbee-local.tgz`
272
- 3. installs it into the OpenCode user-level package workspace at `~/.cache/opencode`
273
- 4. rewrites OpenCode config to the canonical plugin entry `crewbee`
416
+ Full guide: [Installation Guide](docs/guide/installation.md)
274
417
 
275
- ### Published registry install
418
+ ---
276
419
 
277
- After `crewbee` is published to npm:
420
+ ## Quick Start
278
421
 
279
422
  ```bash
280
- npm run install:registry:user
423
+ cd /path/to/project
424
+ opencode
281
425
  ```
282
426
 
283
- OpenCode config can also reference the plugin directly by package name:
427
+ Select `coding-leader` and run your first real task:
284
428
 
285
- ```json
286
- {
287
- "plugin": ["crewbee"]
288
- }
429
+ ```text
430
+ Use CrewBee Coding Team to fix this issue with review-backed completion.
289
431
  ```
290
432
 
291
- ### Verify installation
433
+ Verify anytime:
292
434
 
293
435
  ```bash
294
- npm run doctor
295
- npm run version
436
+ npx crewbee@latest doctor
296
437
  ```
297
438
 
298
- `npm run version` (or `crewbee version`) reads the package version directly from `package.json` for both the current package and the installed package copy.
439
+ For local development, use `npm run install:local:user`; keep that path out of first-time user onboarding.
299
440
 
300
441
  ### Use in OpenCode
301
442
 
302
443
  After installation:
303
444
 
304
- 1. open any project
305
- 2. select a CrewBee projected agent (for example `coding-leader`)
306
- 3. send requests normally
445
+ 1. Open any project.
446
+ 2. Select a CrewBee-projected agent, such as `coding-leader`.
447
+ 3. Send your request normally.
448
+
449
+ ---
307
450
 
308
- ## How Agent Teams and Agent Profiles Are Defined
451
+ ## Agent Team and Agent Profile Definitions
309
452
 
310
- To design and register your own file-based Team, start with the [Custom Agent Team Guide](docs/guide/custom-agent-team.en.md). It walks through the real runnable directory layout, `crewbee.json` registration, Team policy design, agent role boundaries, and validation checklist.
453
+ If you want to design and register your own file-based Team, start with the [Custom Agent Team Guide](docs/guide/custom-agent-team.en.md). It explains the actual runnable directory structure, `crewbee.json` registration, Team policy design, Agent responsibility boundaries, and validation checklist.
311
454
 
312
- If you need project-local Teams that override or complement global Teams, read the [Project-Level Team Configuration Guide](docs/guide/project-team-config.en.md).
455
+ If you need project-level Teams to override or supplement global Teams, continue with the [Project-level Team Configuration Guide](docs/guide/project-team-config.en.md).
313
456
 
314
457
  ### Actual file-based Team structure
315
458
 
316
- The real runnable file-based Team structure is currently:
459
+ The current runnable file-based Team structure is:
317
460
 
318
461
  ```text
319
- <ConfiguredTeamDir>/
462
+ teams/<team-name>/
320
463
  team.manifest.yaml
321
464
  team.policy.yaml
322
465
  <agent>.agent.md
@@ -324,9 +467,9 @@ The real runnable file-based Team structure is currently:
324
467
  TEAM.md # optional
325
468
  ```
326
469
 
327
- The current implementation uses a **flat sibling layout**; it does not require `agents/` or `docs/` subdirectories.
470
+ The current implementation uses a **flat directory**. It does not require `agents/` or `docs/` subdirectories.
328
471
 
329
- Which file-based Teams are loaded is now controlled by:
472
+ The following config controls which file-based Teams are loaded:
330
473
 
331
474
  ```text
332
475
  ~/.config/opencode/crewbee.json
@@ -345,14 +488,14 @@ Example:
345
488
 
346
489
  Notes:
347
490
 
348
- * built-in `coding-team` has no `path`
349
- * file-based Teams use `path` to point at the folder that contains `team.manifest.yaml`
350
- * `@...` paths are resolved relative to the OpenCode config root
351
- * lower `priority` values rank earlier; the highest-priority Team's default leader becomes CrewBee's default OpenCode agent
491
+ * Built-in `coding-team` does not need a `path`.
492
+ * File-based Teams use `path` to point to the directory containing `team.manifest.yaml`.
493
+ * `@...` paths resolve relative to the OpenCode config root.
494
+ * Lower `priority` numbers rank higher. The default leader of the highest-priority Team becomes CrewBee’s default OpenCode agent.
352
495
 
353
496
  ### `team.manifest.yaml`
354
497
 
355
- It defines:
498
+ Responsible for:
356
499
 
357
500
  * Team identity
358
501
  * mission / scope
@@ -362,17 +505,17 @@ It defines:
362
505
  * agent runtime overrides
363
506
  * tags
364
507
 
365
- `members` is not just descriptive. It affects:
508
+ `members` is not just a display field. It affects:
366
509
 
367
510
  * Team structure validation
368
511
  * Team runtime description
369
512
  * Collaboration prompt output
370
513
 
371
- That makes `members.<agent>.responsibility / delegate_when / delegate_mode` important fields rather than decorative metadata.
514
+ Therefore, `members.<agent>.responsibility / delegate_when / delegate_mode` are key fields, not decorative notes.
372
515
 
373
516
  ### `team.policy.yaml`
374
517
 
375
- It defines:
518
+ Responsible for:
376
519
 
377
520
  * instruction precedence
378
521
  * approval policy
@@ -380,23 +523,23 @@ It defines:
380
523
  * quality floor
381
524
  * working rules
382
525
 
383
- And it is eventually compressed into two Team Contract sections:
526
+ It is eventually compressed into two Team Contract sections:
384
527
 
385
528
  * `Working Rules`
386
529
  * `Approval & Safety`
387
530
 
388
531
  ### `*.agent.md`
389
532
 
390
- Each file defines the static image of a single Agent, including:
533
+ Defines a single Agent’s static profile, including:
391
534
 
392
- * what kind of worker the Agent is
393
- * what the Agent is responsible for
394
- * what the Agent’s boundaries are
395
- * how the Agent collaborates by default
396
- * which runtime tools and permissions the Agent needs
397
- * how the Agent normally outputs results
535
+ * what kind of actor this Agent is
536
+ * what this Agent is responsible for
537
+ * what boundaries this Agent has
538
+ * how this Agent collaborates by default
539
+ * what tools and permissions this Agent needs at runtime
540
+ * how this Agent outputs by default
398
541
 
399
- CrewBee recommends expressing key execution semantics as top-level sections, such as:
542
+ CrewBee recommends defining key execution semantics as top-level sections, such as:
400
543
 
401
544
  * `persona_core`
402
545
  * `responsibility_core`
@@ -418,26 +561,27 @@ CrewBee recommends expressing key execution semantics as top-level sections, suc
418
561
  * `anti_patterns`
419
562
  * `tool_skill_strategy`
420
563
 
421
- ### Current capability definition path
564
+ ### Current capability definition paths
422
565
 
423
- The main capability definition path today is:
566
+ Current capability definitions mainly live in:
424
567
 
425
- * **Agent-level capability**: `runtime_config` inside `*.agent.md`
426
- * **Team-level runtime override**: `agent_runtime` inside `team.manifest.yaml`
427
- * **Host-available capability set**: adapter / host capability contract
568
+ * **Agent-level capabilities**: `runtime_config` inside `*.agent.md`
569
+ * **Team-level runtime overrides**: `agent_runtime` inside `team.manifest.yaml`
570
+ * **Host-side available capabilities**: adapter / host capability contract
428
571
 
429
572
  ### `TEAM.md`
430
573
 
431
- `TEAM.md` is a human-facing Team document.
432
- It helps explain:
574
+ `TEAM.md` is a human-facing Team description document.
575
+
576
+ It helps people quickly understand:
433
577
 
434
- * what the Team does
578
+ * what this Team does
435
579
  * who the Leader is
436
580
  * what each member does
437
- * what the default workflow is
581
+ * what the default Workflow is
438
582
 
439
583
  But it is not the source of truth.
440
- The real logic source remains:
584
+ The real logic sources are still:
441
585
 
442
586
  * `team.manifest.yaml`
443
587
  * `team.policy.yaml`
@@ -445,7 +589,7 @@ The real logic source remains:
445
589
 
446
590
  ### Prompt Projection
447
591
 
448
- Current supported shape:
592
+ Currently supported:
449
593
 
450
594
  ```yaml
451
595
  prompt_projection:
@@ -468,7 +612,7 @@ Constraints:
468
612
 
469
613
  ## How the OpenCode Runtime Works
470
614
 
471
- The current OpenCode plugin chain is roughly:
615
+ The current OpenCode plugin path is roughly:
472
616
 
473
617
  ```text
474
618
  package.json
@@ -478,12 +622,12 @@ package.json
478
622
 
479
623
  ### What happens during plugin initialization
480
624
 
481
- 1. load the default Team Library
482
- 2. validate the Team Library
483
- 3. generate bootstrap results
484
- 4. build the alias index
485
- 5. initialize the session binding store
486
- 6. initialize the delegation state store
625
+ 1. Load the default Team Library.
626
+ 2. Validate the Team Library.
627
+ 3. Generate bootstrap results.
628
+ 4. Generate alias index.
629
+ 5. Initialize session binding store.
630
+ 6. Initialize delegation state store.
487
631
 
488
632
  ### Key hooks
489
633
 
@@ -493,7 +637,7 @@ Injects CrewBee projected agents into OpenCode config.
493
637
 
494
638
  #### `chat.message`
495
639
 
496
- Reads the currently selected agent and establishes CrewBee-side session binding.
640
+ Reads the currently selected agent and establishes a CrewBee session binding.
497
641
 
498
642
  #### `tool` / delegation tools
499
643
 
@@ -505,11 +649,11 @@ Registers:
505
649
 
506
650
  #### `tool.execute.before`
507
651
 
508
- Rewrites `task.subagent_type` from aliases into projected config keys.
652
+ Rewrites the `subagent_type` of `task` from alias to projected config key.
509
653
 
510
654
  #### `experimental.chat.system.transform`
511
655
 
512
- Injects minimal CrewBee runtime context into the system prompt:
656
+ Injects minimal CrewBee runtime information into the system prompt:
513
657
 
514
658
  * Team
515
659
  * Entry Agent
@@ -520,53 +664,102 @@ Injects minimal CrewBee runtime context into the system prompt:
520
664
 
521
665
  ## Built-in Coding Team Design
522
666
 
523
- The most important methodological example in CrewBee right now is the built-in Coding Team.
667
+ CrewBee’s most important methodology sample today is the built-in Coding Team.
668
+
669
+ ### 1. The main agent owns the most complete context
670
+
671
+ The Coding Team’s main agent / formal leader is the default entry point, mainline owner, and final closer.
672
+
673
+ It collects:
674
+
675
+ * user goal
676
+ * repository constraints
677
+ * codebase exploration results
678
+ * external research findings
679
+ * reviewer feedback
680
+ * verification results
681
+ * risks and unresolved items
524
682
 
525
- Its core judgments include:
683
+ Key decisions are made by the main agent based on the complete context.
526
684
 
527
- ### 1. Leader is not the same as Planner, nor a pure Orchestrator
685
+ ### 2. Simple tasks do not force complex collaboration
528
686
 
529
- The Leader is the default entry, the main-path owner, and the final closure owner.
530
- But the Leader is not assumed to be “coordination only”.
687
+ CrewBee believes:
531
688
 
532
- ### 2. The role most worth separating is usually not Planner, but Reviewer
689
+ * **simple tasks** should stay lightweight
690
+ * **complex but regular engineering tasks** fit structured Team collaboration
691
+ * **extremely hard problems** should keep context concentrated, trial-and-error fast, and human direction clear
692
+
693
+ Therefore, the Coding Team should not turn every task into a full Team workflow.
694
+
695
+ ### 3. The most valuable independent role is usually Reviewer, not Planner
696
+
697
+ In coding, planning, execution, and verification form a tightly coupled feedback loop.
533
698
 
534
- In coding work, planning, execution, and verification are tightly coupled loops.
535
699
  What matters most is:
536
700
 
537
701
  * context continuity
538
- * end-to-end responsibility closure
539
- * an independent quality perspective
702
+ * end-to-end responsibility
703
+ * independent quality perspective
540
704
 
541
- So the more stable structure is usually:
705
+ A more stable structure is usually:
542
706
 
543
707
  * main execution owner
544
708
  * research
545
709
  * reviewer
546
710
  * advisor when needed
547
711
 
548
- rather than equal O / P / E splitting.
712
+ rather than equal Orchestrator / Planner / Executor separation.
713
+
714
+ ### 4. Support agents use isolated contexts, and the main agent closes the task
549
715
 
550
- ### 3. Simple tasks should not force heavy collaboration, and hard tasks should not default to heavy ceremony either
716
+ For coding tasks, CrewBee emphasizes:
551
717
 
552
- CrewBee’s position is:
718
+ * the main agent holds the main context over time
719
+ * Codebase Explorer independently locates code evidence
720
+ * Web Researcher independently checks external references
721
+ * Reviewer independently checks risks and completion criteria
722
+ * Principal Advisor provides high-level judgment when needed
723
+ * the main agent receives high-signal findings, then decides and closes the task
553
724
 
554
- * **simple tasks** should stay light
555
- * **extremely hard problems** should keep context concentrated, iteration fast, and human guidance clear
556
- * **complex but normal engineering work** is where structured Team collaboration is most useful
725
+ ---
726
+
727
+ ## Next: Project Context
557
728
 
558
- ### 4. main execution owner + research + review is the more important current pattern
729
+ Project Context is an important next-stage product direction for CrewBee.
559
730
 
560
- For coding tasks, CrewBee currently emphasizes:
731
+ Its goal is to automatically maintain project context across sessions, so long-running projects keep high-signal summary information, including:
561
732
 
562
- * formal leader is not equal to pure manager
563
- * the main execution owner can hold the main context for a long time
564
- * research, review, and advisor roles are inserted only as needed
565
- * reviewer remains independent from the main execution path
733
+ * project positioning
734
+ * framework design
735
+ * architecture summary
736
+ * key history
737
+ * current implementation state
738
+ * current plan
739
+ * known risks
740
+ * decision records
741
+ * next actions
742
+ * handoff summary
743
+
744
+ Project Context should not be a one-time generated project summary. It should be continuously updated during project work:
745
+
746
+ ```text
747
+ Session start: read project context and restore project positioning, framework, history, and current plan.
748
+ Task execution: read only the necessary code and materials based on the current goal.
749
+ Session end: update project context with new implementation state, decisions, risks, and next steps.
750
+ Next session: continue from the latest project context.
751
+ ```
752
+
753
+ It reduces two kinds of cost:
754
+
755
+ 1. **Less manual prompting**: users do not need to re-explain project positioning, historical decisions, and current plans every time.
756
+ 2. **Less context spent on reading the whole codebase**: agents can first use project context to understand project structure, key modules, and task-related areas, then read code selectively.
757
+
758
+ > Current note: Project Context is a next-stage enhancement direction. It should not be understood as a fully mature implemented feature today.
566
759
 
567
760
  ---
568
761
 
569
- ## Configuration, Install, and Operations Scripts
762
+ ## Configuration, Installation, and Operations Scripts
570
763
 
571
764
  ### Common scripts
572
765
 
@@ -577,31 +770,37 @@ npm run test
577
770
  npm run pack:local
578
771
  npm run pack:release
579
772
  npm run release:registry:dry-run
773
+ npm run setup
580
774
  npm run install:local:user
581
775
  npm run install:registry:user
776
+ npm run update
582
777
  npm run doctor
778
+ npm run uninstall
583
779
  npm run uninstall:user
584
780
  npm run simulate:opencode
585
781
  npm run simulate:compact
586
782
  ```
587
783
 
588
- ### What they do
589
-
590
- * `build`: build artifacts
591
- * `typecheck`: run TypeScript type checks
592
- * `test`: run tests
593
- * `pack:local`: pack a local tarball
594
- * `pack:release`: pack a versioned release tarball
595
- * `release:registry:dry-run`: run the registry release preflight locally without publishing
596
- * `install:local:user`: run the full user-level install
597
- * `install:registry:user`: install the published npm package into the user-level workspace
598
- * `doctor`: verify OpenCode config and install state
599
- * `version`: show the current package version and installed package version
600
- * `uninstall:user`: uninstall the user-level install
601
- * `simulate:opencode`: run the local OpenCode runtime simulator
602
- * `simulate:compact`: run the compact scenario verification simulator
603
-
604
- ### Default user-level workspace paths
784
+ ### Notes
785
+
786
+ * `build`: builds the package
787
+ * `typecheck`: runs TypeScript type checking
788
+ * `test`: runs tests
789
+ * `pack:local`: packs a local tarball
790
+ * `pack:release`: packs a versioned release tarball
791
+ * `release:registry:dry-run`: runs local registry release checks without publishing
792
+ * `setup`: productized setup for users; installs OpenCode when missing, installs CrewBee, writes config, and runs doctor
793
+ * `install:local:user`: runs the complete user-level installation flow
794
+ * `install:registry:user`: installs the published npm package into the user-level workspace
795
+ * `update`: reinstalls CrewBee from the registry and runs doctor
796
+ * `doctor`: verifies OpenCode config and installation state
797
+ * `version`: shows the current package version and installed package version
798
+ * `uninstall`: removes CrewBee from OpenCode config and user-level workspace
799
+ * `uninstall:user`: uninstalls the user-level installation
800
+ * `simulate:opencode`: runs the local OpenCode runtime simulator
801
+ * `simulate:compact`: runs the compact scenario validation script
802
+
803
+ ### User-level workspace default paths
605
804
 
606
805
  ```text
607
806
  Config root: ~/.config/opencode
@@ -614,19 +813,19 @@ Canonical plugin entry:
614
813
  crewbee
615
814
  ```
616
815
 
617
- Release handbook:
816
+ Release guide:
618
817
 
619
818
  ```text
620
819
  docs/guide/release.md
621
820
  ```
622
821
 
623
- On Windows, the default still prefers:
822
+ On Windows, CrewBee still prefers:
624
823
 
625
824
  ```text
626
825
  ~/.config/opencode
627
826
  ```
628
827
 
629
- If an existing OpenCode configuration is already located at `%APPDATA%/opencode`, CrewBee falls back to that existing config location for compatibility.
828
+ If an existing OpenCode config is found under `%APPDATA%/opencode`, CrewBee falls back to that location for compatibility.
630
829
 
631
830
  ---
632
831
 
@@ -643,7 +842,7 @@ This will:
643
842
  * remove the CrewBee plugin entry from OpenCode config
644
843
  * remove the installed package from the user-level workspace
645
844
 
646
- If you want to verify the uninstall state afterward, run:
845
+ To verify the uninstall state:
647
846
 
648
847
  ```bash
649
848
  npm run doctor
@@ -653,8 +852,8 @@ npm run doctor
653
852
 
654
853
  ## Acknowledgements
655
854
 
656
- CrewBee is inspired by OpenCode and by community projects such as Oh My OpenAgent, which have explored how agent-team workflows can improve real development environments.
855
+ CrewBee is inspired by OpenCode and community projects such as oh-my-openagent. These projects explored the value of Agent Team workflows in real development environments and helped more developers see the potential of multi-agent collaboration.
657
856
 
658
- Thanks to the builders and maintainers who made these ideas visible and practical.
857
+ Thanks to their developers and maintainers.
659
858
 
660
- CrewBee continues this direction by treating Agent Teams as manageable engineering assets: defined once, projected into host runtimes, configured for different task modes, and evolved as reusable team packages.
859
+ CrewBee continues in this direction by organizing Agent Teams from prompt fragments or role configurations into manageable, projectable, configurable, and reusable engineering assets, so Agent Teams for different tasks or projects can be defined, run, and evolved more clearly.