Author
The Author responsibility is to give Colony a clear problem and to resolve product ambiguity. It is commonly performed by a product owner, support engineer, technical lead, or anyone who would normally brief another developer.
This is a human responsibility model, not a role or permission enforced by Colony.
Define the work
Section titled “Define the work”Colony does not require a five-field issue schema. The analyzer can work from an ordinary issue title, body, comments, repository context, and conventions. For more predictable results, include the information that matters to the change:
- why the change is needed
- observable outcomes or acceptance criteria
- important constraints and non-goals
- how correctness should be tested, when that is not obvious
- relevant files, APIs, or prior work, when you know them
File references are helpful anchors, especially in a large repository, but they are not mandatory. Do not guess a path merely to fill a template.
See Writing for Colony for examples.
Answer clarification questions
Section titled “Answer clarification questions”If the analyzer cannot choose a safe implementation path, it comments on the issue and moves it to needs-clarification. Reply to that question in an issue comment. A qualifying non-bot reply is the event Colony uses to resume the originating stage.
You can also update the issue body so future readers see the current specification. Editing the body without replying does not, by itself, trigger clarification recovery.
Understand the plan
Section titled “Understand the plan”For ordinary work, analysis can publish a plan and proceed to development without waiting for an Author to accept it. There is no built-in plan-approval gate.
If the analysis is materially wrong and the issue has not already advanced too far, correct the issue and use /colony:reanalyze where the active workflow allows it. An ordinary comment on an issue in ready-for-dev does not automatically rerun the analyzer.
For epic-scale work, Colony may create child issues and place the parent in waiting-for-subtasks. Review those child issues as normal code-host issues. Correct or cancel unsuitable work explicitly rather than assuming a comment recreates the decomposition.
Validate the result
Section titled “Validate the result”Whether a human sees the pull request before merge depends on merge policy and pipeline outcome:
- with automatic merge disabled, approved work stops at
human-review-ready - review failures, unresolved conditions, or explicit commands can also require human attention
- with automatic merge enabled and provider requirements satisfied, a straightforward PR may merge without an Author gate
Validate high-value outcomes before enabling automatic merge for that class of work. When a PR needs a small correction, leave precise feedback and use the supported steering command for the current state. When the requested outcome itself has changed, prefer a new issue rather than silently expanding an in-flight PR.
Useful tools
Section titled “Useful tools”- issue bodies and comments for specification and clarification
- pull-request reviews for human judgment
- Slash Commands for explicit pipeline actions
- Pipeline States for understanding the current state