crewbee 0.1.9 → 0.1.11

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 (158) hide show
  1. package/README.md +448 -233
  2. package/README.zh-CN.md +334 -127
  3. package/dist/opencode-plugin.mjs +406 -210
  4. package/dist/src/adapters/opencode/bootstrap.js.map +1 -1
  5. package/dist/src/adapters/opencode/chat-message-hook.d.ts.map +1 -1
  6. package/dist/src/adapters/opencode/chat-message-hook.js +2 -1
  7. package/dist/src/adapters/opencode/chat-message-hook.js.map +1 -1
  8. package/dist/src/adapters/opencode/config-hook.d.ts.map +1 -1
  9. package/dist/src/adapters/opencode/config-hook.js +12 -5
  10. package/dist/src/adapters/opencode/config-hook.js.map +1 -1
  11. package/dist/src/adapters/opencode/defaults.d.ts +3 -0
  12. package/dist/src/adapters/opencode/defaults.d.ts.map +1 -0
  13. package/dist/src/adapters/opencode/defaults.js +5 -0
  14. package/dist/src/adapters/opencode/defaults.js.map +1 -0
  15. package/dist/src/adapters/opencode/index.d.ts +1 -0
  16. package/dist/src/adapters/opencode/index.d.ts.map +1 -1
  17. package/dist/src/adapters/opencode/index.js +3 -1
  18. package/dist/src/adapters/opencode/index.js.map +1 -1
  19. package/dist/src/adapters/opencode/plugin.d.ts.map +1 -1
  20. package/dist/src/adapters/opencode/plugin.js +1 -1
  21. package/dist/src/adapters/opencode/plugin.js.map +1 -1
  22. package/dist/src/adapters/opencode/prompt-builder.d.ts.map +1 -1
  23. package/dist/src/adapters/opencode/prompt-builder.js +7 -17
  24. package/dist/src/adapters/opencode/prompt-builder.js.map +1 -1
  25. package/dist/src/adapters/opencode/system-transform-hook.d.ts +2 -1
  26. package/dist/src/adapters/opencode/system-transform-hook.d.ts.map +1 -1
  27. package/dist/src/adapters/opencode/system-transform-hook.js +17 -3
  28. package/dist/src/adapters/opencode/system-transform-hook.js.map +1 -1
  29. package/dist/src/agent-teams/canonical-agent-id.d.ts.map +1 -1
  30. package/dist/src/agent-teams/canonical-agent-id.js +3 -0
  31. package/dist/src/agent-teams/canonical-agent-id.js.map +1 -1
  32. package/dist/src/agent-teams/diagnostics.d.ts +10 -0
  33. package/dist/src/agent-teams/diagnostics.d.ts.map +1 -0
  34. package/dist/src/agent-teams/diagnostics.js +29 -0
  35. package/dist/src/agent-teams/diagnostics.js.map +1 -0
  36. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts +1 -3
  37. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.d.ts.map +1 -1
  38. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js +4 -14
  39. package/dist/src/agent-teams/embedded/coding-team/agent-helpers.js.map +1 -1
  40. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts +4 -0
  41. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.d.ts.map +1 -0
  42. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js +17 -0
  43. package/dist/src/agent-teams/embedded/coding-team/agent-profile-builder.js.map +1 -0
  44. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js +5 -5
  45. package/dist/src/agent-teams/embedded/coding-team/agents/codebase-explorer.js.map +1 -1
  46. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js +4 -4
  47. package/dist/src/agent-teams/embedded/coding-team/agents/coding-executor.js.map +1 -1
  48. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js +8 -8
  49. package/dist/src/agent-teams/embedded/coding-team/agents/coding-leader.js.map +1 -1
  50. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js +8 -8
  51. package/dist/src/agent-teams/embedded/coding-team/agents/coordination-leader.js.map +1 -1
  52. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js +2 -2
  53. package/dist/src/agent-teams/embedded/coding-team/agents/multimodal-looker.js.map +1 -1
  54. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js +5 -5
  55. package/dist/src/agent-teams/embedded/coding-team/agents/principal-advisor.js.map +1 -1
  56. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js +6 -6
  57. package/dist/src/agent-teams/embedded/coding-team/agents/reviewer.js.map +1 -1
  58. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js +5 -5
  59. package/dist/src/agent-teams/embedded/coding-team/agents/web-researcher.js.map +1 -1
  60. package/dist/src/agent-teams/filesystem.d.ts +4 -0
  61. package/dist/src/agent-teams/filesystem.d.ts.map +1 -1
  62. package/dist/src/agent-teams/filesystem.js +134 -21
  63. package/dist/src/agent-teams/filesystem.js.map +1 -1
  64. package/dist/src/agent-teams/index.d.ts +1 -0
  65. package/dist/src/agent-teams/index.d.ts.map +1 -1
  66. package/dist/src/agent-teams/index.js +5 -1
  67. package/dist/src/agent-teams/index.js.map +1 -1
  68. package/dist/src/agent-teams/library.d.ts +5 -1
  69. package/dist/src/agent-teams/library.d.ts.map +1 -1
  70. package/dist/src/agent-teams/library.js +31 -8
  71. package/dist/src/agent-teams/library.js.map +1 -1
  72. package/dist/src/agent-teams/parsers.js +3 -3
  73. package/dist/src/agent-teams/parsers.js.map +1 -1
  74. package/dist/src/agent-teams/types.d.ts +6 -0
  75. package/dist/src/agent-teams/types.d.ts.map +1 -1
  76. package/dist/src/agent-teams/validation.d.ts.map +1 -1
  77. package/dist/src/agent-teams/validation.js +50 -3
  78. package/dist/src/agent-teams/validation.js.map +1 -1
  79. package/dist/src/cli/doctor.d.ts.map +1 -1
  80. package/dist/src/cli/doctor.js +53 -7
  81. package/dist/src/cli/doctor.js.map +1 -1
  82. package/dist/src/cli/install.d.ts.map +1 -1
  83. package/dist/src/cli/install.js +8 -3
  84. package/dist/src/cli/install.js.map +1 -1
  85. package/dist/src/cli/parse-install-options.d.ts.map +1 -1
  86. package/dist/src/cli/parse-install-options.js +31 -0
  87. package/dist/src/cli/parse-install-options.js.map +1 -1
  88. package/dist/src/cli/parse-setup-options.d.ts +3 -0
  89. package/dist/src/cli/parse-setup-options.d.ts.map +1 -0
  90. package/dist/src/cli/parse-setup-options.js +102 -0
  91. package/dist/src/cli/parse-setup-options.js.map +1 -0
  92. package/dist/src/cli/render-help.d.ts.map +1 -1
  93. package/dist/src/cli/render-help.js +12 -4
  94. package/dist/src/cli/render-help.js.map +1 -1
  95. package/dist/src/cli/run-cli.d.ts.map +1 -1
  96. package/dist/src/cli/run-cli.js +27 -1
  97. package/dist/src/cli/run-cli.js.map +1 -1
  98. package/dist/src/cli/setup.d.ts +7 -0
  99. package/dist/src/cli/setup.d.ts.map +1 -0
  100. package/dist/src/cli/setup.js +70 -0
  101. package/dist/src/cli/setup.js.map +1 -0
  102. package/dist/src/cli/uninstall-user.d.ts.map +1 -1
  103. package/dist/src/cli/uninstall-user.js +2 -1
  104. package/dist/src/cli/uninstall-user.js.map +1 -1
  105. package/dist/src/cli/validate.d.ts +6 -0
  106. package/dist/src/cli/validate.d.ts.map +1 -0
  107. package/dist/src/cli/validate.js +90 -0
  108. package/dist/src/cli/validate.js.map +1 -0
  109. package/dist/src/core/index.d.ts +1 -0
  110. package/dist/src/core/index.d.ts.map +1 -1
  111. package/dist/src/install/config-writer.d.ts +2 -18
  112. package/dist/src/install/config-writer.d.ts.map +1 -1
  113. package/dist/src/install/config-writer.js +9 -94
  114. package/dist/src/install/config-writer.js.map +1 -1
  115. package/dist/src/install/doctor.d.ts.map +1 -1
  116. package/dist/src/install/doctor.js +28 -19
  117. package/dist/src/install/doctor.js.map +1 -1
  118. package/dist/src/install/index.d.ts +6 -4
  119. package/dist/src/install/index.d.ts.map +1 -1
  120. package/dist/src/install/index.js +20 -11
  121. package/dist/src/install/index.js.map +1 -1
  122. package/dist/src/install/install.d.ts.map +1 -1
  123. package/dist/src/install/install.js +50 -33
  124. package/dist/src/install/install.js.map +1 -1
  125. package/dist/src/install/opencode-cli.d.ts +14 -0
  126. package/dist/src/install/opencode-cli.d.ts.map +1 -0
  127. package/dist/src/install/opencode-cli.js +58 -0
  128. package/dist/src/install/opencode-cli.js.map +1 -0
  129. package/dist/src/install/opencode-config-file.d.ts +26 -0
  130. package/dist/src/install/opencode-config-file.d.ts.map +1 -0
  131. package/dist/src/install/opencode-config-file.js +131 -0
  132. package/dist/src/install/opencode-config-file.js.map +1 -0
  133. package/dist/src/install/package-installation.d.ts +19 -0
  134. package/dist/src/install/package-installation.d.ts.map +1 -0
  135. package/dist/src/install/package-installation.js +95 -0
  136. package/dist/src/install/package-installation.js.map +1 -0
  137. package/dist/src/install/package-manager.d.ts +1 -14
  138. package/dist/src/install/package-manager.d.ts.map +1 -1
  139. package/dist/src/install/package-manager.js +8 -79
  140. package/dist/src/install/package-manager.js.map +1 -1
  141. package/dist/src/install/plugin-entry.d.ts +3 -1
  142. package/dist/src/install/plugin-entry.d.ts.map +1 -1
  143. package/dist/src/install/plugin-entry.js +11 -22
  144. package/dist/src/install/plugin-entry.js.map +1 -1
  145. package/dist/src/install/setup.d.ts +6 -0
  146. package/dist/src/install/setup.d.ts.map +1 -0
  147. package/dist/src/install/setup.js +72 -0
  148. package/dist/src/install/setup.js.map +1 -0
  149. package/dist/src/install/types.d.ts +41 -0
  150. package/dist/src/install/types.d.ts.map +1 -1
  151. package/dist/src/install/uninstall.d.ts.map +1 -1
  152. package/dist/src/install/uninstall.js +30 -18
  153. package/dist/src/install/uninstall.js.map +1 -1
  154. package/dist/src/render/prompt-document-renderer.d.ts +4 -0
  155. package/dist/src/render/prompt-document-renderer.d.ts.map +1 -0
  156. package/dist/src/render/prompt-document-renderer.js +19 -0
  157. package/dist/src/render/prompt-document-renderer.js.map +1 -0
  158. package/package.json +5 -2
package/README.md CHANGED
@@ -6,147 +6,336 @@
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.md)
42
- - [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`.
53
+
54
+ ---
43
55
 
44
56
  ## Agent IDs in OpenCode
45
57
 
46
- 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.
47
59
 
48
60
  Examples:
49
61
 
50
- - `coding-leader`
51
- - `coding-executor`
52
- - `coding-reviewer`
62
+ * `coding-leader`
63
+ * `coding-executor`
64
+ * `coding-reviewer`
53
65
 
54
- 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.
55
67
 
56
68
  ---
57
69
 
58
70
  ## Table of Contents
59
71
 
60
72
  * [What CrewBee Is](#what-crewbee-is)
61
- * [What Problems CrewBee Solves](#what-problems-crewbee-solves)
73
+ * [What CrewBee Solves](#what-crewbee-solves)
62
74
  * [Core Features](#core-features)
63
75
  * [Installation](#installation)
64
76
  * [Quick Start](#quick-start)
65
- * [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)
66
78
  * [How the OpenCode Runtime Works](#how-the-opencode-runtime-works)
67
79
  * [Built-in Coding Team Design](#built-in-coding-team-design)
68
- * [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)
69
82
  * [Uninstall](#uninstall)
83
+ * [Acknowledgements](#acknowledgements)
70
84
 
71
85
  ---
72
86
 
73
87
  ## What CrewBee Is
74
88
 
75
- In CrewBee, the real first-class object is not a single Agent, but a **Team**.
76
- 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:
77
92
 
78
93
  * Team identity and positioning
79
94
  * formal leader
80
95
  * members
81
96
  * workflow
82
- * Team shared rules
97
+ * Team-level shared rules
83
98
  * Agent Profiles
84
99
  * Prompt Projection
85
100
  * host runtime mapping
86
101
 
87
- 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.
88
- 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.
89
103
 
90
- * the user selects a Team entry Agent in the host
91
- * CrewBee projects the Team definition into the host runtime
92
- * 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.
93
111
 
94
112
  ---
95
113
 
96
- ## 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.
97
127
 
98
- 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.
99
129
 
100
- ### 1. Turning scattered Agent practices into maintainable Team assets
130
+ ### 3. Keep the main agent as the owner of the most complete context
101
131
 
102
- 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.
103
133
 
104
- ### 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.
105
135
 
106
- 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
107
137
 
108
- ### 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.
109
139
 
110
- 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.
111
159
 
112
160
  ---
113
161
 
114
162
  ## Core Features
115
163
 
116
- ### 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
294
+
295
+ CrewBee first converts the Team-first structure into a unified intermediate representation, then maps it into concrete host runtimes.
296
+
297
+ The current primary host is OpenCode.
298
+
299
+ The current OpenCode MVP path includes:
117
300
 
118
- CrewBee treats Teams as first-class objects rather than isolated agent prompts.
119
- That means:
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
120
312
 
121
- * Teams have a formal leader
122
- * Teams have policy
123
- * Teams have members and workflow
124
- * Teams have a host-agnostic structural model
313
+ This makes CrewBee more than a prompt folder. It is a runtime framework that can actually plug into OpenCode.
125
314
 
126
- ### 2. Host-agnostic Runtime Projection
315
+ ### 7. Copyable, modifiable, and contributable Team templates
127
316
 
128
- CrewBee first converts Team-first structures into a unified intermediate model, then maps that model into specific hosts.
129
- This keeps Team / Agent definitions as host-agnostic as possible and makes long-term maintenance and future expansion easier.
317
+ CrewBee Teams are file-based engineering assets that can be copied, modified, versioned, and contributed.
130
318
 
131
- ### 3. OpenCode adapter and plugin runtime
319
+ Users can:
132
320
 
133
- CrewBee already supports the full path from Team / Agent definitions to runnable OpenCode agents, including:
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
134
327
 
135
- * projected agent → OpenCode agent config
136
- * Team / Agent prompt construction
137
- * config patch generation
138
- * host event integration
139
- * delegation tool wiring
328
+ Many users may not modify CrewBee core, but they can still start from a template and build their own Team.
140
329
 
141
- ### 4. Prompts stay low-coupling while preserving execution semantics
330
+ ### 8. Prompts are decoupled while preserving execution semantics
142
331
 
143
- CrewBee does not fall back to “one renderer per field”, nor does it dump every top-level block transparently.
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.
144
333
 
145
- Instead, it uses:
334
+ The current approach is:
146
335
 
147
- > **a small shared semantic skeleton + general structural handling + structured rendering**
336
+ > **a small set of shared semantic sections + generic structural processing + structured rendering**
148
337
 
149
- For example, the Agent prompt skeleton is organized around execution thinking:
338
+ For example, the Agent prompt skeleton is organized around execution cognition:
150
339
 
151
340
  * Persona Core
152
341
  * Responsibility Core
@@ -172,145 +361,105 @@ This helps the model quickly establish:
172
361
 
173
362
  * who I am
174
363
  * what I am responsible for
175
- * how I normally act
364
+ * how I act by default
176
365
  * when to delegate / review / ask / stop
177
- * what counts as done
366
+ * what counts as completion
178
367
  * how to recover from failure
179
368
 
180
- ### 5. Collaboration produces directly usable delegation targets
369
+ ### 9. Collaboration generates runtime-usable delegation targets
181
370
 
182
- 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:
183
372
 
184
- * collaboration targets declared in Agent Profiles
373
+ * subagent collaboration declarations from the Agent Profile
185
374
  * `members` descriptions from the Team Manifest
186
375
  * projected ids that OpenCode can resolve
187
376
 
188
- This lets the runtime surface delegation-ready agent entries.
377
+ Then it generates:
189
378
 
190
- ### 6. Team Contract is compressed into an executable handbook
379
+ * `Id`
380
+ * `Description`
381
+ * `When To Delegate`
191
382
 
192
- Instead of mechanically rendering the whole governance block, CrewBee compresses Team prompt output into:
383
+ This makes delegation targets directly usable at runtime.
384
+
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:
193
388
 
194
389
  * `Working Rules`
195
390
  * `Approval & Safety`
196
391
 
197
- 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.
198
393
 
199
- ### 7. User-level install and operations flow
394
+ ### 11. User-level installation and operations flow
200
395
 
201
- 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.
202
397
 
203
398
  ---
204
399
 
205
400
  ## Installation
206
401
 
207
- ### Shortest path for humans
208
-
209
- If you are using an LLM Agent, just send it this:
210
-
211
- ```text
212
- Please install CrewBee by following docs/guide/installation.md.
213
- Use the OpenCode user-level installation flow only, not the old project-local flow.
214
- ```
215
-
216
- Or read the guide yourself:
217
-
218
- * [Installation Guide](docs/guide/installation.md)
219
-
220
- ### Shortest path for LLM Agents
221
-
222
- Read and follow:
223
-
224
- ```text
225
- docs/guide/installation.md
226
- docs/guide/release.md
227
- ```
228
-
229
- ### One-click local install script for Windows
230
-
231
- The repository already provides:
232
-
233
- ```bat
234
- scripts\install-local-user.bat
235
- ```
236
-
237
- It runs:
238
-
239
- 1. `npm install`
240
- 2. `npm run install:local:user`
241
- 3. `npm run doctor`
242
-
243
- ---
244
-
245
- ## Quick Start
246
-
247
- ### Development build
402
+ Install CrewBee for OpenCode in one command:
248
403
 
249
404
  ```bash
250
- npm install
251
- npm run typecheck
252
- npm run build
405
+ npx crewbee@latest setup --with-opencode
253
406
  ```
254
407
 
255
- ### Local user-level install
256
-
257
- Recommended from the repository root:
408
+ If you already have OpenCode:
258
409
 
259
410
  ```bash
260
- npm install
261
- npm run install:local:user
411
+ npx crewbee@latest setup
262
412
  ```
263
413
 
264
- 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.
265
415
 
266
- 1. builds CrewBee
267
- 2. packs a stable local tarball to `.artifacts/local/crewbee-local.tgz`
268
- 3. installs it into the OpenCode user-level package workspace at `~/.cache/opencode`
269
- 4. rewrites OpenCode config to the canonical plugin entry `crewbee`
416
+ Full guide: [Installation Guide](docs/guide/installation.md)
270
417
 
271
- ### Published registry install
418
+ ---
272
419
 
273
- After `crewbee` is published to npm:
420
+ ## Quick Start
274
421
 
275
422
  ```bash
276
- npm run install:registry:user
423
+ cd /path/to/project
424
+ opencode
277
425
  ```
278
426
 
279
- OpenCode config can also reference the plugin directly by package name:
427
+ Select `coding-leader` and run your first real task:
280
428
 
281
- ```json
282
- {
283
- "plugin": ["crewbee"]
284
- }
429
+ ```text
430
+ Use CrewBee Coding Team to fix this issue with review-backed completion.
285
431
  ```
286
432
 
287
- ### Verify installation
433
+ Verify anytime:
288
434
 
289
435
  ```bash
290
- npm run doctor
291
- npm run version
436
+ npx crewbee@latest doctor
292
437
  ```
293
438
 
294
- `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.
295
440
 
296
441
  ### Use in OpenCode
297
442
 
298
443
  After installation:
299
444
 
300
- 1. open any project
301
- 2. select a CrewBee projected agent (for example `coding-leader`)
302
- 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.
303
448
 
304
- ## How Agent Teams and Agent Profiles Are Defined
449
+ ---
305
450
 
306
- To design and register your own file-based Team, start with the [Custom Agent Team Guide](docs/guide/custom-agent-team.md). It walks through the real runnable directory layout, `crewbee.json` registration, Team policy design, agent role boundaries, and validation checklist.
451
+ ## Agent Team and Agent Profile Definitions
452
+
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.
454
+
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).
307
456
 
308
457
  ### Actual file-based Team structure
309
458
 
310
- The real runnable file-based Team structure is currently:
459
+ The current runnable file-based Team structure is:
311
460
 
312
461
  ```text
313
- <ConfiguredTeamDir>/
462
+ teams/<team-name>/
314
463
  team.manifest.yaml
315
464
  team.policy.yaml
316
465
  <agent>.agent.md
@@ -318,9 +467,9 @@ The real runnable file-based Team structure is currently:
318
467
  TEAM.md # optional
319
468
  ```
320
469
 
321
- 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.
322
471
 
323
- Which file-based Teams are loaded is now controlled by:
472
+ The following config controls which file-based Teams are loaded:
324
473
 
325
474
  ```text
326
475
  ~/.config/opencode/crewbee.json
@@ -339,14 +488,14 @@ Example:
339
488
 
340
489
  Notes:
341
490
 
342
- * built-in `coding-team` has no `path`
343
- * file-based Teams use `path` to point at the folder that contains `team.manifest.yaml`
344
- * `@...` paths are resolved relative to the OpenCode config root
345
- * 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.
346
495
 
347
496
  ### `team.manifest.yaml`
348
497
 
349
- It defines:
498
+ Responsible for:
350
499
 
351
500
  * Team identity
352
501
  * mission / scope
@@ -356,17 +505,17 @@ It defines:
356
505
  * agent runtime overrides
357
506
  * tags
358
507
 
359
- `members` is not just descriptive. It affects:
508
+ `members` is not just a display field. It affects:
360
509
 
361
510
  * Team structure validation
362
511
  * Team runtime description
363
512
  * Collaboration prompt output
364
513
 
365
- 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.
366
515
 
367
516
  ### `team.policy.yaml`
368
517
 
369
- It defines:
518
+ Responsible for:
370
519
 
371
520
  * instruction precedence
372
521
  * approval policy
@@ -374,23 +523,23 @@ It defines:
374
523
  * quality floor
375
524
  * working rules
376
525
 
377
- And it is eventually compressed into two Team Contract sections:
526
+ It is eventually compressed into two Team Contract sections:
378
527
 
379
528
  * `Working Rules`
380
529
  * `Approval & Safety`
381
530
 
382
531
  ### `*.agent.md`
383
532
 
384
- Each file defines the static image of a single Agent, including:
533
+ Defines a single Agent’s static profile, including:
385
534
 
386
- * what kind of worker the Agent is
387
- * what the Agent is responsible for
388
- * what the Agent’s boundaries are
389
- * how the Agent collaborates by default
390
- * which runtime tools and permissions the Agent needs
391
- * 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
392
541
 
393
- 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:
394
543
 
395
544
  * `persona_core`
396
545
  * `responsibility_core`
@@ -412,26 +561,27 @@ CrewBee recommends expressing key execution semantics as top-level sections, suc
412
561
  * `anti_patterns`
413
562
  * `tool_skill_strategy`
414
563
 
415
- ### Current capability definition path
564
+ ### Current capability definition paths
416
565
 
417
- The main capability definition path today is:
566
+ Current capability definitions mainly live in:
418
567
 
419
- * **Agent-level capability**: `runtime_config` inside `*.agent.md`
420
- * **Team-level runtime override**: `agent_runtime` inside `team.manifest.yaml`
421
- * **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
422
571
 
423
572
  ### `TEAM.md`
424
573
 
425
- `TEAM.md` is a human-facing Team document.
426
- It helps explain:
574
+ `TEAM.md` is a human-facing Team description document.
427
575
 
428
- * what the Team does
576
+ It helps people quickly understand:
577
+
578
+ * what this Team does
429
579
  * who the Leader is
430
580
  * what each member does
431
- * what the default workflow is
581
+ * what the default Workflow is
432
582
 
433
583
  But it is not the source of truth.
434
- The real logic source remains:
584
+ The real logic sources are still:
435
585
 
436
586
  * `team.manifest.yaml`
437
587
  * `team.policy.yaml`
@@ -439,7 +589,7 @@ The real logic source remains:
439
589
 
440
590
  ### Prompt Projection
441
591
 
442
- Current supported shape:
592
+ Currently supported:
443
593
 
444
594
  ```yaml
445
595
  prompt_projection:
@@ -462,7 +612,7 @@ Constraints:
462
612
 
463
613
  ## How the OpenCode Runtime Works
464
614
 
465
- The current OpenCode plugin chain is roughly:
615
+ The current OpenCode plugin path is roughly:
466
616
 
467
617
  ```text
468
618
  package.json
@@ -472,12 +622,12 @@ package.json
472
622
 
473
623
  ### What happens during plugin initialization
474
624
 
475
- 1. load the default Team Library
476
- 2. validate the Team Library
477
- 3. generate bootstrap results
478
- 4. build the alias index
479
- 5. initialize the session binding store
480
- 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.
481
631
 
482
632
  ### Key hooks
483
633
 
@@ -487,7 +637,7 @@ Injects CrewBee projected agents into OpenCode config.
487
637
 
488
638
  #### `chat.message`
489
639
 
490
- Reads the currently selected agent and establishes CrewBee-side session binding.
640
+ Reads the currently selected agent and establishes a CrewBee session binding.
491
641
 
492
642
  #### `tool` / delegation tools
493
643
 
@@ -499,11 +649,11 @@ Registers:
499
649
 
500
650
  #### `tool.execute.before`
501
651
 
502
- Rewrites `task.subagent_type` from aliases into projected config keys.
652
+ Rewrites the `subagent_type` of `task` from alias to projected config key.
503
653
 
504
654
  #### `experimental.chat.system.transform`
505
655
 
506
- Injects minimal CrewBee runtime context into the system prompt:
656
+ Injects minimal CrewBee runtime information into the system prompt:
507
657
 
508
658
  * Team
509
659
  * Entry Agent
@@ -514,53 +664,102 @@ Injects minimal CrewBee runtime context into the system prompt:
514
664
 
515
665
  ## Built-in Coding Team Design
516
666
 
517
- 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
518
670
 
519
- Its core judgments include:
671
+ The Coding Team’s main agent / formal leader is the default entry point, mainline owner, and final closer.
520
672
 
521
- ### 1. Leader is not the same as Planner, nor a pure Orchestrator
673
+ It collects:
522
674
 
523
- The Leader is the default entry, the main-path owner, and the final closure owner.
524
- But the Leader is not assumed to be “coordination only”.
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
525
682
 
526
- ### 2. The role most worth separating is usually not Planner, but Reviewer
683
+ Key decisions are made by the main agent based on the complete context.
684
+
685
+ ### 2. Simple tasks do not force complex collaboration
686
+
687
+ CrewBee believes:
688
+
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.
527
698
 
528
- In coding work, planning, execution, and verification are tightly coupled loops.
529
699
  What matters most is:
530
700
 
531
701
  * context continuity
532
- * end-to-end responsibility closure
533
- * an independent quality perspective
702
+ * end-to-end responsibility
703
+ * independent quality perspective
534
704
 
535
- So the more stable structure is usually:
705
+ A more stable structure is usually:
536
706
 
537
707
  * main execution owner
538
708
  * research
539
709
  * reviewer
540
710
  * advisor when needed
541
711
 
542
- rather than equal O / P / E splitting.
712
+ rather than equal Orchestrator / Planner / Executor separation.
543
713
 
544
- ### 3. Simple tasks should not force heavy collaboration, and hard tasks should not default to heavy ceremony either
714
+ ### 4. Support agents use isolated contexts, and the main agent closes the task
545
715
 
546
- CrewBee’s position is:
716
+ For coding tasks, CrewBee emphasizes:
547
717
 
548
- * **simple tasks** should stay light
549
- * **extremely hard problems** should keep context concentrated, iteration fast, and human guidance clear
550
- * **complex but normal engineering work** is where structured Team collaboration is most useful
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
724
+
725
+ ---
551
726
 
552
- ### 4. main execution owner + research + review is the more important current pattern
727
+ ## Next: Project Context
553
728
 
554
- For coding tasks, CrewBee currently emphasizes:
729
+ Project Context is an important next-stage product direction for CrewBee.
555
730
 
556
- * formal leader is not equal to pure manager
557
- * the main execution owner can hold the main context for a long time
558
- * research, review, and advisor roles are inserted only as needed
559
- * reviewer remains independent from the main execution path
731
+ Its goal is to automatically maintain project context across sessions, so long-running projects keep high-signal summary information, including:
732
+
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.
560
759
 
561
760
  ---
562
761
 
563
- ## Configuration, Install, and Operations Scripts
762
+ ## Configuration, Installation, and Operations Scripts
564
763
 
565
764
  ### Common scripts
566
765
 
@@ -571,31 +770,37 @@ npm run test
571
770
  npm run pack:local
572
771
  npm run pack:release
573
772
  npm run release:registry:dry-run
773
+ npm run setup
574
774
  npm run install:local:user
575
775
  npm run install:registry:user
776
+ npm run update
576
777
  npm run doctor
778
+ npm run uninstall
577
779
  npm run uninstall:user
578
780
  npm run simulate:opencode
579
781
  npm run simulate:compact
580
782
  ```
581
783
 
582
- ### What they do
583
-
584
- * `build`: build artifacts
585
- * `typecheck`: run TypeScript type checks
586
- * `test`: run tests
587
- * `pack:local`: pack a local tarball
588
- * `pack:release`: pack a versioned release tarball
589
- * `release:registry:dry-run`: run the registry release preflight locally without publishing
590
- * `install:local:user`: run the full user-level install
591
- * `install:registry:user`: install the published npm package into the user-level workspace
592
- * `doctor`: verify OpenCode config and install state
593
- * `version`: show the current package version and installed package version
594
- * `uninstall:user`: uninstall the user-level install
595
- * `simulate:opencode`: run the local OpenCode runtime simulator
596
- * `simulate:compact`: run the compact scenario verification simulator
597
-
598
- ### 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
599
804
 
600
805
  ```text
601
806
  Config root: ~/.config/opencode
@@ -608,19 +813,19 @@ Canonical plugin entry:
608
813
  crewbee
609
814
  ```
610
815
 
611
- Release handbook:
816
+ Release guide:
612
817
 
613
818
  ```text
614
819
  docs/guide/release.md
615
820
  ```
616
821
 
617
- On Windows, the default still prefers:
822
+ On Windows, CrewBee still prefers:
618
823
 
619
824
  ```text
620
825
  ~/.config/opencode
621
826
  ```
622
827
 
623
- 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.
624
829
 
625
830
  ---
626
831
 
@@ -637,8 +842,18 @@ This will:
637
842
  * remove the CrewBee plugin entry from OpenCode config
638
843
  * remove the installed package from the user-level workspace
639
844
 
640
- If you want to verify the uninstall state afterward, run:
845
+ To verify the uninstall state:
641
846
 
642
847
  ```bash
643
848
  npm run doctor
644
849
  ```
850
+
851
+ ---
852
+
853
+ ## Acknowledgements
854
+
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.
856
+
857
+ Thanks to their developers and maintainers.
858
+
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.