Skip to content

AGENTS.md

Latest commit

 

History

History
205 lines (144 loc) · 10.3 KB

AGENTS.md

File metadata and controls

205 lines (144 loc) · 10.3 KB

AGENTS.md

Purpose

This repository defines an OpenCode workflow system for feature delivery with 4 stages:

  1. Specs
  2. Plan
  3. Tasks
  4. Implement

The goal is to force the AI to clarify requirements first, design before coding, split work into atomic tasks, and only then implement with validation.

All workflow artifacts are intended to stay in chat unless a user explicitly asks for file output.

Current Architecture

The active OpenCode configuration lives under .opencode.

Main agent

Agent Path Role
workflow-orchestrator .opencode/agents/workflow-orchestrator.md Primary entrypoint. Routes requests to the correct stage, tracks gate status, preserves workflow state in chat, and decides when downstream work must be invalidated.

Subagents

Agent Path Role
workflow-specs .opencode/agents/workflow-specs.md Clarifies requirements, asks focused questions, defines expected behavior, and prepares Gate 1 approval.
workflow-plan .opencode/agents/workflow-plan.md Inspects repo context first, uses fresh external references only when needed, proposes the design, and prepares Gate 2 approval.
workflow-tasks .opencode/agents/workflow-tasks.md Converts an approved plan into numbered atomic tasks with boundaries, validation, and done conditions, then prepares Gate 3 approval.
workflow-implement .opencode/agents/workflow-implement.md Executes one approved atomic task at a time, validates against Specs and task contract, and reports result plus next step.

Skills

Workflow maintenance skill

Skill Path Role
workflow-contracts .opencode/skills/workflow-contracts/SKILL.md Maintenance reference for the workflow system itself. Documents gate semantics, stage outputs, and handoff rules. This is not intended to be a required runtime dependency.

Builder skills

These skills help generate new OpenCode building blocks inside the project:

Skill Path Role
create-agent .opencode/skills/create-agent/SKILL.md Create new primary agents or subagents under .opencode/agents/.
create-command .opencode/skills/create-command/SKILL.md Create reusable slash commands under .opencode/commands/.
create-skill .opencode/skills/create-skill/SKILL.md Create reusable OpenCode skills under .opencode/skills/<name>/SKILL.md.
create-tool .opencode/skills/create-tool/SKILL.md Create custom tools under .opencode/tools/ using @opencode-ai/plugin.

Commands

Command Path Role
/workflow .opencode/commands/workflow.md Start a new workflow or continue the current one in the same thread through workflow-orchestrator.
/workflow-step .opencode/commands/workflow-step.md Ask the orchestrator to revisit or enter a specific stage. The orchestrator still enforces missing approvals and may route backward.

Tools

There is currently no project-local custom tool registered under .opencode/tools/.

The project already includes .opencode/package.json with @opencode-ai/plugin, so the codebase is ready to add tools later if needed.

The workflow does use built-in OpenCode tools operationally:

  • question for clarification and batch approvals
  • todoread and todowrite only from workflow-orchestrator

Workflow Semantics

Gate model

Gate Meaning
Gate 1 Specs has been reviewed and approved by the user.
Gate 2 Plan has been reviewed and approved by the user.
Gate 3 Task list has been reviewed and approved by the user. Implementation may start only after this point.

After Gate 3 approval, the orchestrator creates a todo list with one todo item per atomic task.

Gate approvals are prose-based. They are asked by the stage agent in the stage output and recorded by workflow-orchestrator.

Ownership model

Stage Owner Allowed actions
Specs workflow-specs Clarify, ask, define behavior, request approval.
Plan workflow-plan Inspect repo, browse when freshness matters, propose design, request approval.
Tasks workflow-tasks Split into atomic tasks, attach validation, request approval.
Implement workflow-implement Edit code and validate exactly one task by default.

Handoff model

The orchestrator is responsible for carrying forward this normalized state between phases and synchronizing it with the todo list:

WORKFLOW HANDOFF
Goal:
Approved Specs:
Approved Plan:
Task List:
Gate Status:
Unresolved Questions:
Requested Stage:
Reason:

Subagents should not own long-term memory. They operate on the current handoff only.

How To Use In A Real Project

Normal feature flow

Use this path for most real work:

  1. Start with /workflow <feature or request>.
  2. Answer the Specs questions.
  3. Explicitly approve Specs.
  4. Review the proposed Plan.
  5. Explicitly approve Plan.
  6. Review the atomic task list.
  7. Explicitly approve Tasks.
  8. Let the orchestrator create the todo list.
  9. Approve each proposed parallel batch when the orchestrator asks for it.
  10. Let the orchestrator dispatch one or more workflow-implement subagents depending on task independence.

Example:

/workflow Add email OTP login to the existing React auth flow

Revisiting a stage

Use /workflow-step when a later stage needs to be corrected.

Examples:

/workflow-step specs We also need account lockout after 3 failed OTP attempts
/workflow-step plan Rework this plan to use the existing NestJS auth module
/workflow-step tasks Split task 3 into smaller backend and frontend tasks

Direct agent usage

Prefer /workflow over calling agents manually.

Use workflow-orchestrator as the only public entrypoint. Do not call hidden subagents directly unless you are debugging the workflow system itself.

Best Practices

For users

  • Give the feature request in terms of user outcome, not implementation too early.
  • Answer Specs questions concretely. Vague answers create weak plans and oversized tasks.
  • Approve each gate explicitly. Do not assume “looks good” will always be interpreted correctly.
  • Gate approvals are plain-text replies. Batch approvals still use a structured tool-driven confirmation flow.
  • Expect one more approval step for each parallel implementation batch after Gate 3.
  • Change scope as early as possible. Changes after Gate 2 or Gate 3 will invalidate downstream work.
  • Let Implement run one atomic task at a time for risky or complex changes.
  • In the Plan stage, expect code snippets only for the most critical changes, not as a full design diff.

For maintainers

  • Keep workflow-orchestrator thin. Routing and gate control belong there; stage-specific thinking belongs in subagents.
  • Keep subagents single-purpose. Do not let Specs drift into planning or let Implement redefine requirements.
  • Treat workflow-contracts as documentation for prompt alignment, not a mandatory runtime dependency.
  • When adding new agents or commands, prefer project-local files in .opencode/ over scattered config snippets.
  • If you add custom tools later, reserve them for deterministic tasks or structured IO, not for replacing the gate workflow.

For task design

  • Keep each atomic task small enough to implement and validate in one run.
  • Include Task ID, Dependencies, Ownership Hint, and Parallel Constraints whenever you evolve the workflow contract.
  • Include a concrete Validation step and a crisp Done When condition.
  • Split backend, frontend, schema, and migration work when coupling is low.
  • If a task cannot be validated independently, it is probably too large.

For external research

  • workflow-plan should inspect the repo first.
  • Use web or MCP only when the answer may be outdated or version-sensitive.
  • Prefer official docs and primary sources when browsing is required.
  • Bring external research back to the approved Specs instead of pasting generic best practices.
  • If code is shown in the Plan stage, keep it to minimal target-shape snippets that clarify critical boundaries only.

Operational Notes

  • The current workflow is chat-first. It intentionally avoids writing SPEC.md, PLAN.md, or TASKS.md by default.
  • Todo tracking starts only after the task list is approved and is owned entirely by workflow-orchestrator.
  • Subagents are hidden and intended to be invoked by the orchestrator via task delegation.
  • The runtime environment has shown issues with auto-loading skills as hard dependencies, so prompts embed the critical contract directly. workflow-contracts remains the maintenance reference.
  • The /workflow command is the intended UX, but workflow-orchestrator is the most reliable entrypoint for validation and debugging.

Suggested Conventions For Future Expansion

  • Add workflow-review only if you want a formal review stage after each implementation task.
  • Add project-local custom tools only when you need deterministic helpers such as schema inspection, diff summarization, or artifact export.
  • Keep names lowercase and hyphenated across agents, commands, skills, and tools.
  • Favor explicit permissions and hidden subagents for internal helpers.