DOCSEARCHbyAlgolia
Submit Docs

opencode-workspace Documentation

repository·main·Indexed 19 days ago

https://github.com/kdcokenny/opencode-workspace

A bundled multi-agent orchestration harness for OpenCode providing a pre-configured environment of agents, skills, and MCP servers for AI-driven development. It features a hierarchical architecture of Orchestrators (plan, build) and Specialists (explore, researcher, coder, scribe, reviewer), including specialized roles like the Coder Agent for philosophy-driven implementation and the Researcher Agent for read-only external knowledge gathering.

Tokens
13.8K
Snippets
28
Records
68
Agent score
67%

What's inside opencode-workspace

  1. Overview of the opencode-workspace Bundle

    main

    The opencode-workspace is a curated bundle of 16 components designed as a complete AI development harness. It includes:

    • Plugins: workspace-plugin, background-agents, notify, worktree, @tarquinen/opencode-dcp, and @franlol/opencode-md-table-formatter.
    • MCP Servers: context7 (library docs), exa (web search), and gh_grep (GitHub search).
    • Agents: researcher, coder, scribe, and reviewer.
    • Skills: plan-protocol, code-review, code-philosophy, and frontend-philosophy.
    • Commands: The /review slash command.
    • Security: Pre-configured permission boundaries like webfetch: deny and agent sandboxing.

  2. How the Plan and Phase lifecycles work

    main

    The Plan Protocol follows a strict state machine to ensure progress tracking is accurate.

    Plan Lifecycle

    not-started → in-progress → complete (or blocked)

    Phase Lifecycle

    [PENDING] → [IN PROGRESS] → [COMPLETE] (or [BLOCKED])

    Task Lifecycle

    [ ] (unchecked) → [x] (checked)

    Critical Constraints

    1. Only ONE phase may be [IN PROGRESS] at any time.
    2. Only ONE task may have the ← CURRENT marker at any time.
    3. Move ← CURRENT immediately when starting a new task.
    4. Mark tasks [x] immediately after completing them.

  3. Understand the Scribe Agent role and limitations

    main

    The Scribe Agent is a specialized subagent focused exclusively on human-facing prose (documentation, commit messages, PR descriptions, etc.).

    Key Constraints:

    • No Code/Commands: The Scribe Agent is forbidden from creating code, editing code, running bash commands, or deleting files.
    • No AI Attribution: Do not include phrases like "Generated by Claude" or "Co-Authored-By: Claude".
    • No Emojis: Do not use emojis unless explicitly requested.
    • Leaf Agent: The Scribe Agent cannot spawn or delegate to other agents.

  4. How the Workspace Architecture works

    main

    The workspace operates using a hierarchical model of Orchestrators and Specialists:

    1. Orchestrators: The plan and build agents manage high-level tasks and coordinate the workflow.
    2. Specialists: These agents execute specific roles under the direction of orchestrators. They include explore, researcher, coder, scribe, and reviewer.

    This structure allows for complex task delegation where orchestrators manage the lifecycle and specialists handle the granular execution (e.g., coding, researching, or documenting).

  5. The 5 Laws of Philosophy Checklist

    main

    The Code Review Agent evaluates code against five core architectural principles known as 'The 5 Laws'. Use these as a mental model for writing code that passes review:

    1. Early Exit (Guard Clauses): Handle edge cases at function tops, keep nesting depth < 3 levels, and use early returns instead of nested if statements.
    2. Parse, Don't Validate: Perform input parsing at boundaries so that types are trusted within internal logic, avoiding redundant validation.
    3. Atomic Predictability: Aim for pure functions where possible, isolate side effects, and ensure the same input always produces the same output.
    4. Fail Fast, Fail Loud: Throw immediately on invalid states, use descriptive error messages, and ensure error handling is visible rather than silent.
    5. Intentional Naming: Use names that read like English, avoid abbreviations, and ensure function names describe the return value.

  6. Understand the Researcher Agent role and limitations

    main

    The Researcher Agent is a read-only subagent designed for external knowledge gathering. It acts as a knowledge architect that finds implementation-ready research, documentation, and code patterns from external sources.

    Key Characteristics

    • Read-Only: The agent CANNOT modify the local filesystem, write files, create directories, or use any Write or Edit tools. It is strictly a research entity.
    • Autonomous: The agent has full authority to pursue follow-up threads, perform additional searches, and synthesize multiple sources without asking for permission.
    • Persistence: You do not need to save files. The delegation system automatically persists the agent's text output.
    • Output Goal: The agent follows the "Completed Staff Work" doctrine, meaning the output should be so complete that the recipient can act on it immediately without follow-up questions.

  7. Cite research using Delegations

    main

    When making architectural decisions or performing tasks informed by research, you must cite the relevant delegation ID using the ref:ID format.

    Workflow

    1. Delegate research using delegate to a researcher or explore.
    2. Obtain a readable ID from the completed delegation (e.g., swift-amber-falcon).
    3. Cite the research in the plan:
      • In Context & Decisions table: Add to the Source column as `ref:DELEGATION_ID`.
      • In Task lists: Append → ref:id to the task line.
      • In Notes: Use inline citations like `ref:DELEGATION_ID`.

    Tools for Citations

    • delegation_list(): View all existing delegations.
    • delegation_read("id"): Verify content before citing.

    Warning: Never make up delegation IDs or cite without reading the delegation content.

  9. Plan Review Checklist: Citation, Completeness, and Actionability

    main

    When performing a plan review, evaluate the content against these three criteria:

    1. Citation Quality

    Ensure all architectural decisions and research phases are substantiated.

    • Requirement: Decisions must use the ref:delegation-id format.
    • Requirement: Research tasks must include citations (e.g., → ref:id) when marked complete.
    • Red Flags: Empty or - in the Source column of the decisions table; claims like "industry standard" without a citation.

    2. Completeness

    Verify the plan covers the full scope of the intended work.

    • Goal: Must be specific and measurable (e.g., Add JWT authentication with refresh token support instead of Improve authentication).
    • Phases: Must be logical and sequential.
    • Edge Cases: Error handling and failure modes must be addressed.
    • Documentation: Must include a Notes section and a Context & Decisions table.

    3. Actionability

    Ensure a developer can execute the plan without further clarification.

    • Tasks: Must be specific about which files or components are affected (e.g., Create src/auth/jwt.ts with sign/verify functions instead of Set up the backend).
    • Scope: Avoid ambiguous verbs like "investigate" or "figure out" without defined scope.
    • Dependencies: Sequential tasks must show a clear logical order.

  12. Coder Agent forbidden actions

    main

    To maintain system integrity, the Coder Agent is strictly prohibited from the following:

    • NEVER commit code (the orchestrator handles git operations).
    • NEVER write tests unless explicitly instructed.
    • NEVER research or search external resources (use the researcher agent).
    • NEVER write documentation or human-facing prose (use the scribe agent).
    • NEVER make architectural decisions without approval.
    • NEVER leave debug statements (console.log, print, debugger, etc.).
    • NEVER skip verification (always run lint/type-check after changes).
    • NEVER ignore philosophy violations.
    • NEVER spawn or delegate to other agents (you are a leaf agent).