Generated contract reference
Generated by python tools/generate_contract_reference.py. Do not edit this file by hand.
Check without writing: python tools/generate_contract_reference.py --check.
This reference covers declared role/queue/task transitions, normalized runtime record fields,
run state transitions and validated preset examples. Dynamic task/evidence checks still run
in the domain services. The field tables are Python record contracts, not a complete YAML
validation grammar: mapping keys supply IDs, manifests require transport: acp, and the
manifest guide explains input configuration and constraints.
Queues
| Queue |
Kind |
Owner |
Writers |
| .stand |
state |
null |
["TESTER", "ARCHITECT-PLANNER", "MAINTAINER", "LIVE-DEVELOPER", "EXPLORER", "ARCHITECT-REVIEWER"] |
| archive |
terminal |
ARCHITECT-PLANNER |
["ARCHITECT-PLANNER", "ARCHITECT-REVIEWER"] |
| feature_blocked |
parking |
ARCHITECT-REVIEWER |
["DEVELOPER", "UI-DEVELOPER", "TECHNICAL-WRITER", "TESTER", "READER", "ARCHITECT-REVIEWER", "ARCHITECT-PLANNER"] |
| feature_dev |
active |
DEVELOPER |
["DEVELOPER"] |
| feature_docs |
active |
TECHNICAL-WRITER |
["TECHNICAL-WRITER"] |
| feature_docs_review |
active |
READER |
["TECHNICAL-WRITER", "READER"] |
| feature_inbox |
active |
ARCHITECT-PLANNER |
["ARCHITECT-PLANNER", "EXPLORER"] |
| feature_live |
active |
LIVE-DEVELOPER |
["LIVE-DEVELOPER", "ARCHITECT-PLANNER"] |
| feature_plan |
active |
ARCHITECT-PLANNER |
["ARCHITECT-PLANNER"] |
| feature_review |
active |
ARCHITECT-REVIEWER |
["TESTER", "READER", "LIVE-DEVELOPER", "ARCHITECT-REVIEWER"] |
| feature_test |
active |
TESTER |
["DEVELOPER", "UI-DEVELOPER", "TESTER"] |
| feature_ui_dev |
active |
UI-DEVELOPER |
["UI-DEVELOPER"] |
| review_sessions |
active |
EXPLORER |
["ARCHITECT-PLANNER", "EXPLORER"] |
| user_feedback |
active |
ARCHITECT-PLANNER |
["USER"] |
| verified |
terminal |
ARCHITECT-REVIEWER |
["ARCHITECT-REVIEWER"] |
Roles
Declarations below come directly from the normative schema; tokens are defined in its glossary.
ARCHITECT-PLANNER
category: product
claims_from:
- user_feedback
- feature_inbox
- feature_plan
event_triggers:
on_feature_inbox_claim:
- append_triage_block
- mv_to_feature_plan_or_archive
on_feature_plan_claim:
- write_plan_block
- set_stand_required
- route_to_feature_dev_or_feature_ui_dev_or_feature_docs
- decompose_scope_release_umbrella_into_subtasks_then_archive_umbrella
on_stand_down_yaml_playbook_error:
- read_down_reason_from_inbox_info
- file_bugfix_task_for_coordination_stand_profiles_yaml
- assign_to_developer
on_stand_unregistered_profile:
- read_registry_error
- file_feature_dev_task_for_stand_profile_registry_entry
- include_required_profile_name_file_used_for_default_for
on_user_feedback_claim:
- read_user_feedback_block
- append_triage_block
- mv_user_feedback_to_feature_inbox_or_archive
forbidden_actions:
- implement_code
- run_ansible
- mark_stand_ready
- claim_review_sessions
- archive_in_lifecycle_work_directly_except_decomposed_release_umbrella
intake_discipline: propose_then_file
lifecycle: interactive
responsibilities:
- triage_user_feedback
- write_plan_blocks
- route_tasks_per_scope
- chat_partner_for_user
- file_review_sessions
- coordinate_stand_profile_tasks_via_registry_and_canon
- file_profile_registry_task_on_unregistered_profile
ARCHITECT-REVIEWER
category: product
claims_from:
- feature_review
- feature_blocked
event_triggers:
on_feature_blocked_claim:
- inspect_dependency_findings_and_resolve_semantic_blockers
- archive_when_withdrawn_reason_present
on_feature_review_claim:
- verify_blocks_chain
- run_gate_check
- append_review_block_approved_or_changes_requested
- mv_to_verified_on_approved
- mv_back_to_implementer_queue_on_changes_requested
on_verified_rollback:
- append_rollback_block_with_reason
- mv_to_archive_or_feature_review
forbidden_actions:
- implement_code
- claim_outside_review_queues
- approve_without_gate_check_pass_when_stand_required
lifecycle: driven
responsibilities:
- verify_evidence_chain
- commit_and_merge
- resolve_dependency_cycles_and_invalid_declarations
- rollback_verified_tasks
stand_profile_selection:
allowed_used_for:
- reviewer_validation
- tester_validation
- explorer_review
- production_post_deploy_review
default_for:
final_review_when_stand_required: reviewer
production_review: production_review
must_select_from: coordination/stand-profiles.yaml
required_for:
- final_review_when_stand_required
- production_review
DEVELOPER
category: product
claims_from:
- feature_dev
event_triggers:
on_feature_dev_claim:
- implement_code_in_worktree
- run_pytest_suite
- append_implementation_block
- mv_to_feature_test
forbidden_actions:
- claim_ui_or_docs_or_stand_tasks
- deploy_stand
- run_product_validation_on_stand
- read_or_move_from_feature_plan
- commit_to_main_directly
lifecycle: driven
responsibilities:
- implement_backend_features
- write_unit_tests
- file_implementation_block_with_files_list
EXPLORER
category: product
claims_from:
- review_sessions
event_triggers:
on_review_sessions_claim:
- acquire_lease_via_stand_lease
- run_scenarios_against_deployed_stand
- file_bugs_as_feature_inbox_tasks
- append_session_iteration_block
- release_lease
- mv_to_archive_when_complete
forbidden_actions:
- implement_code
- deploy_stand
- claim_outside_review_sessions
- validate_off_stand_or_local_substitutes
- Run host-destructive or recovery actions (kill, pkill, systemctl, logout, reboot)
against the local orchestration host or an unresolved target. Such scenarios require
an explicitly authorized disposable stand and verified target identity; otherwise
submit a blocker.
lifecycle: driven
responsibilities:
- run_review_sessions_on_live_stand
- operate_on_the_stand_as_real_user_whatever_its_shape
- file_bugs_to_feature_inbox
stand_profile_selection:
allowed_used_for:
- explorer_review
- full_product_validation
default_for:
review_session: explorer
must_select_from: coordination/stand-profiles.yaml
required_for:
- review_session
LIVE-DEVELOPER
category: product
claims_from:
- feature_live
event_triggers:
on_feature_live_claim:
- create_worktree
- acquire_lease_via_stand_lease
- deploy_to_own_leased_stand_during_session
- interactive_chat_with_user
- on_user_ok_append_implementation_block
- release_lease
- mv_to_feature_review
forbidden_actions:
- claim_outside_feature_live
- commit_to_main_directly
- skip_sprint_review
lifecycle: interactive
responsibilities:
- work_a_single_task_live_with_user_on_leased_stand
- deploy_to_own_leased_stand_during_session
- hand_to_review_as_sprint_on_user_ok
stand_profile_selection:
allowed_used_for:
- live_ui
- ui_iteration
default_for:
feature_live: live_developer
must_select_from: coordination/stand-profiles.yaml
required_for:
- feature_live
MAINTAINER
category: system
claims_from: []
event_triggers:
on_operator_diagnostic_request:
- inspect_runtime_status_and_operation_evidence
- diagnose_cause_and_propose_bounded_repair
forbidden_actions:
- claim_product_queues
- triage_user_feedback
- write_plan_blocks
- schedule_polling_or_recovery_loops
- infer_safe_replay_from_missing_process
lifecycle: interactive
responsibilities:
- diagnose_unknown_infrastructure_failures
- propose_repairs_with_explicit_preconditions
- explain_unresolved_runtime_and_deployment_outcomes
- infra_chat_for_user
READER
category: product
claims_from:
- feature_docs_review
event_triggers:
on_feature_docs_review_claim:
- read_docs_fresh_no_prior_context
- append_reader_review_block
- mv_to_feature_review_on_pass
- mv_back_to_feature_docs_on_fail_or_partial
- route_audit_only_to_feature_review_never_feature_docs
forbidden_actions:
- claim_implementer_queues
- write_code
lifecycle: driven
responsibilities:
- validate_doc_clarity_as_fresh_user
- append_reader_review_block
TECHNICAL-WRITER
category: product
claims_from:
- feature_docs
event_triggers:
on_feature_docs_claim:
- write_docs_in_worktree
- run_docs_build_if_configured
- append_implementation_block
- mv_to_feature_docs_review
forbidden_actions:
- claim_backend_or_ui_tasks
- commit_to_main_directly
lifecycle: driven
responsibilities:
- write_documentation
- file_implementation_block
TESTER
category: product
claims_from:
- feature_test
event_triggers:
on_feature_test_claim:
- inspect_plan_stand_requirement_and_acceptance
- request_configured_daemon_checks_and_assess_receipts_for_local_tasks
- acquire_lease_when_plan_requires_stand
- wait_for_state_ready_when_plan_requires_stand
- probe_via_ssh_when_plan_requires_stand
- fill_tests_block_with_real_observed_output
- run_gate_check
- release_lease_with_result_if_held
- submit_typed_handoff_to_feature_review
forbidden_actions:
- deploy_stand
- run_ansible_locally
- fill_fake_stand_evidence
- claim_outside_feature_test
- execute_local_tests_directly_outside_declared_command_service
- replace_required_stand_probes_with_local_checks
- uv_run_or_active_against_fleet_venv
lifecycle: driven
responsibilities:
- independently_assess_implementation_and_test_adequacy
- request_configured_daemon_checks_for_local_tasks
- probe_feature_on_deployed_stand_when_plan_requires_it
- fill_real_stand_evidence_when_plan_requires_it
- run_gate_check_before_mv
stand_profile_selection:
allowed_used_for:
- tester_validation
- deploy_only
- warmup
- quick_readiness
default_for:
plan.stand_required: feature_test
plan.verify_only: verify_only
must_select_from: coordination/stand-profiles.yaml
required_for:
- plan.stand_required
- plan.verify_only
UI-DEVELOPER
category: product
claims_from:
- feature_ui_dev
event_triggers:
on_feature_ui_dev_claim:
- implement_ui_in_worktree
- run_ui_test_suite
- append_implementation_block
- mv_to_feature_test
forbidden_actions:
- claim_backend_or_docs_tasks
- deploy_stand
- commit_to_main_directly
lifecycle: driven
responsibilities:
- implement_ui_features
- run_ui_tests
- file_implementation_block
USER
category: entry
claims_from: []
event_triggers: {}
forbidden_actions:
- claim_any_queue
- implement_code
- write_blocks_directly_to_active_queues
lifecycle: interactive
responsibilities:
- file_user_feedback
- chat_with_planner
Task transitions
Dynamic queue/owner selectors remain literal; the task policy resolves them against the current task and queue.
| From |
To |
Role |
Required validators |
| user_feedback |
feature_inbox |
ARCHITECT-PLANNER |
["triage_block"] |
| user_feedback |
archive |
ARCHITECT-PLANNER |
["triage_block"] |
| feature_inbox |
archive |
ARCHITECT-PLANNER |
[] |
| feature_plan |
archive |
ARCHITECT-PLANNER |
[] |
| review_sessions |
archive |
ARCHITECT-PLANNER |
["review_session_terminal_block"] |
| review_sessions |
archive |
EXPLORER |
["review_session_terminal_block"] |
| feature_blocked |
archive |
ARCHITECT-REVIEWER |
["feature_blocked_withdrawn_reason"] |
| feature_inbox |
feature_plan |
ARCHITECT-PLANNER |
["triage_block"] |
| feature_plan |
feature_dev |
ARCHITECT-PLANNER |
["plan_block", "scope_backend"] |
| feature_plan |
feature_ui_dev |
ARCHITECT-PLANNER |
["plan_block", "scope_ui"] |
| feature_plan |
feature_docs |
ARCHITECT-PLANNER |
["plan_block", "scope_docs"] |
| feature_plan |
feature_docs_review |
ARCHITECT-PLANNER |
["plan_block", "scope_docs", "plan.audit_only"] |
| feature_plan |
feature_live |
ARCHITECT-PLANNER |
["plan_block", "plan.interactive"] |
| feature_plan |
feature_test |
ARCHITECT-PLANNER |
["plan_block", "plan.verify_only"] |
| feature_dev |
feature_test |
DEVELOPER |
["implementation_block"] |
| feature_ui_dev |
feature_test |
UI-DEVELOPER |
["implementation_block"] |
| feature_docs |
feature_docs_review |
TECHNICAL-WRITER |
["implementation_block"] |
| feature_live |
feature_review |
LIVE-DEVELOPER |
["implementation_block"] |
| feature_test |
feature_review |
TESTER |
["tests_block", "gate_check_pass_if_stand_required"] |
| feature_test |
feature_dev |
TESTER |
["tests_block_fail_or_partial", "scope_backend"] |
| feature_test |
feature_ui_dev |
TESTER |
["tests_block_fail_or_partial", "scope_ui"] |
| feature_docs_review |
feature_review |
READER |
["reader_block_pass"] |
| feature_docs_review |
feature_docs |
READER |
["reader_block_fail_or_partial"] |
| feature_review |
verified |
ARCHITECT-REVIEWER |
["review_block_approved", "gate_check_pass_if_stand_required"] |
| feature_review |
feature_dev |
ARCHITECT-REVIEWER |
["review_block_changes_requested", "scope_backend"] |
| feature_review |
feature_ui_dev |
ARCHITECT-REVIEWER |
["review_block_changes_requested", "scope_ui"] |
| feature_review |
feature_docs |
ARCHITECT-REVIEWER |
["review_block_changes_requested", "scope_docs"] |
| any_active_queue |
feature_blocked |
current_owner |
["blocked_block_with_dependencies_and_resume_to"] |
| any_active_queue |
feature_blocked |
ARCHITECT-PLANNER |
["blocked_block_withdrawn_reason_and_resume_to"] |
| feature_blocked |
any_resume_to_queue |
ARCHITECT-REVIEWER |
["all_dependencies_exist_per_wake_check"] |
| verified |
archive |
ARCHITECT-REVIEWER |
["rollback_block_with_reason"] |
| verified |
feature_review |
ARCHITECT-REVIEWER |
["rollback_block_with_reason"] |
Declared daemon operations
These operations belong to SYSTEM, not to an agent role.
resume_dependencies:
from: feature_blocked
requires:
- terminal_dependencies
- declared_resume
- task_readiness
to: declared_resume_to
Run state transitions
| State |
Permitted next states |
| cancelling |
["cancelled", "failed", "interrupted"] |
| claimed |
["cancelled", "interrupted", "starting"] |
| running |
["cancelling", "completed", "failed", "interrupted", "waiting_auth", "waiting_input"] |
| starting |
["cancelling", "failed", "interrupted", "running", "waiting_auth", "waiting_input"] |
| waiting_auth |
["cancelling", "failed", "interrupted", "starting"] |
| waiting_input |
["cancelling", "failed", "interrupted", "running"] |
Terminal states: cancelled, completed, failed, interrupted.
Normalized runtime fields
Required means the Python record has no default. Defaults use JSON notation (tuples become arrays); null and empty collections are distinct.
AgentManifest
| Field |
Python type |
Default |
| id |
str |
required |
| argv |
tuple[str, ...] |
required |
| adapter_version |
str |
required |
| harness_version |
str |
required |
| environment |
tuple[tuple[str, str], ...] |
[] |
| required_env |
tuple[str, ...] |
[] |
| required_capabilities |
tuple[str, ...] |
[] |
| optional_capabilities |
tuple[str, ...] |
[] |
| auth_method |
str | None |
null |
| account_limit_errors |
tuple[AccountLimitError, ...] |
[] |
RoleBinding
| Field |
Python type |
Default |
| id |
str |
required |
| role |
str |
required |
| agent |
str |
required |
| workspace |
str |
"." |
| scheduling |
str |
"on-demand" |
| permission |
str |
"ask" |
| session |
str |
"resume-if-compatible" |
| model |
str | None |
null |
| mode |
str | None |
null |
| reasoning |
str | None |
null |
| account |
str |
"default" |
| max_running |
int |
1 |
| timeout_seconds |
int |
1800 |
| max_prompt_bytes |
int |
262144 |
| max_session_input_bytes |
int |
1048576 |
| max_reported_session_cost |
float | None |
null |
| reported_cost_currency |
str | None |
null |
| max_no_progress_turns |
int |
1 |
| max_startup_retries |
int |
2 |
| retry_initial_seconds |
int |
5 |
| retry_max_seconds |
int |
60 |
CommandDefinition
| Field |
Python type |
Default |
| id |
str |
required |
| argv |
tuple[str, ...] |
required |
| roles |
tuple[str, ...] |
required |
| cwd |
str |
"." |
| timeout_seconds |
int |
600 |
| max_output_bytes |
int |
1048576 |
| environment |
tuple[tuple[str, str], ...] |
[] |
| required_env |
tuple[str, ...] |
[] |
| environment_revision |
str |
"1" |
| purpose |
str |
"validation" |
| authorized |
bool |
false |
AccountLimitError
| Field |
Python type |
Default |
| code |
int |
required |
| kind |
str |
required |
| cooldown_seconds |
int | None |
null |
StandDeploymentPolicy
| Field |
Python type |
Default |
| profiles |
tuple[str, ...] |
[] |
| authorized |
bool |
false |
| timeout_seconds |
int |
1800 |
| max_output_bytes |
int |
1048576 |
| environment_revision |
str |
"1" |
ExecutionConfig
| Field |
Python type |
Default |
| agents |
tuple[AgentManifest, ...] |
required |
| bindings |
tuple[RoleBinding, ...] |
required |
| max_running |
int |
4 |
| account_limits |
tuple[tuple[str, int], ...] |
[] |
| commands |
tuple[CommandDefinition, ...] |
[] |
| stand |
StandDeploymentPolicy | None |
null |
| account_retry_initial_seconds |
int |
5 |
| account_retry_max_seconds |
int |
60 |
| max_runtime_events |
int |
10000 |
TaskRevision
| Field |
Python type |
Default |
| task_id |
str |
required |
| path |
str |
required |
| sha256 |
str |
required |
ResultEnvelope
| Field |
Python type |
Default |
| result_id |
str |
required |
| run_id |
str |
required |
| task_id |
str |
required |
| task_revision |
str |
required |
| schema_sha256 |
str |
required |
| decision |
str |
required |
| payload |
dict |
required |
Validated preset examples
Executable and version values are placeholders. No harness is launched by generation.
Stand profiles and validation commands need separate project configuration.
deployed
agents:
configured-acp:
adapter_version: replace-with-tested-version
argv:
- replace-with-installed-acp-executable
harness_version: replace-with-tested-version
transport: acp
bindings:
developer:
agent: configured-acp
role: DEVELOPER
scheduling: queue
explorer:
agent: configured-acp
role: EXPLORER
scheduling: queue
live-developer:
agent: configured-acp
role: LIVE-DEVELOPER
scheduling: on-demand
planner:
agent: configured-acp
role: ARCHITECT-PLANNER
scheduling: on-demand
reviewer:
agent: configured-acp
role: ARCHITECT-REVIEWER
scheduling: queue
tester:
agent: configured-acp
role: TESTER
scheduling: queue
ui-developer:
agent: configured-acp
role: UI-DEVELOPER
scheduling: queue
version: 1
docs
agents:
configured-acp:
adapter_version: replace-with-tested-version
argv:
- replace-with-installed-acp-executable
harness_version: replace-with-tested-version
transport: acp
bindings:
planner:
agent: configured-acp
role: ARCHITECT-PLANNER
scheduling: on-demand
reader:
agent: configured-acp
role: READER
scheduling: queue
reviewer:
agent: configured-acp
role: ARCHITECT-REVIEWER
scheduling: queue
writer:
agent: configured-acp
role: TECHNICAL-WRITER
scheduling: queue
version: 1
full
agents:
configured-acp:
adapter_version: replace-with-tested-version
argv:
- replace-with-installed-acp-executable
harness_version: replace-with-tested-version
transport: acp
bindings:
developer:
agent: configured-acp
role: DEVELOPER
scheduling: queue
explorer:
agent: configured-acp
role: EXPLORER
scheduling: queue
live-developer:
agent: configured-acp
role: LIVE-DEVELOPER
scheduling: on-demand
maintainer:
agent: configured-acp
role: MAINTAINER
scheduling: on-demand
planner:
agent: configured-acp
role: ARCHITECT-PLANNER
scheduling: on-demand
reader:
agent: configured-acp
role: READER
scheduling: queue
reviewer:
agent: configured-acp
role: ARCHITECT-REVIEWER
scheduling: queue
tester:
agent: configured-acp
role: TESTER
scheduling: queue
ui-developer:
agent: configured-acp
role: UI-DEVELOPER
scheduling: queue
writer:
agent: configured-acp
role: TECHNICAL-WRITER
scheduling: queue
version: 1
local
agents:
configured-acp:
adapter_version: replace-with-tested-version
argv:
- replace-with-installed-acp-executable
harness_version: replace-with-tested-version
transport: acp
bindings:
developer:
agent: configured-acp
role: DEVELOPER
scheduling: queue
planner:
agent: configured-acp
role: ARCHITECT-PLANNER
scheduling: on-demand
reviewer:
agent: configured-acp
role: ARCHITECT-REVIEWER
scheduling: queue
tester:
agent: configured-acp
role: TESTER
scheduling: queue
version: 1
ui
agents:
configured-acp:
adapter_version: replace-with-tested-version
argv:
- replace-with-installed-acp-executable
harness_version: replace-with-tested-version
transport: acp
bindings:
planner:
agent: configured-acp
role: ARCHITECT-PLANNER
scheduling: on-demand
reviewer:
agent: configured-acp
role: ARCHITECT-REVIEWER
scheduling: queue
tester:
agent: configured-acp
role: TESTER
scheduling: queue
ui-developer:
agent: configured-acp
role: UI-DEVELOPER
scheduling: queue
version: 1
Source fingerprints
The check also detects changes to validators and controllers referenced by these declarations.
| Source |
SHA-256 |
| src/greatminds/cli/task.py |
c96e5267236816a503979f1b1f77048fc84abf059c7dce3d3dd73c44086fe0d7 |
| src/greatminds/data/schema.yaml |
7ff6c38d41376e95889f7abc11c02305caf368f64290db02976232e553d5ae94 |
| src/greatminds/domain/maintenance.py |
4e61f33e40eaefd8ff286262420a32526b3d158ef04629cbe85b85e879160f29 |
| src/greatminds/domain/results.py |
3f376fb886e3925be8be60f63b4a352267131c9f3509c29d25291a7c40e1b0f1 |
| src/greatminds/runtime/account_limits.py |
1c4083f6d345e2cada11cff5938ff2f01d3bcaa0184ba72418500f7d138fe790 |
| src/greatminds/runtime/config.py |
56e416b6feee01726d4d155f3b0cb2cd28cee921f68c90476e21cf27e9260d21 |
| src/greatminds/runtime/presets.py |
89da0ea85d1c2a22105795870d0d54e51b69e214088c7e1ca07eebd33352fd97 |
| src/greatminds/runtime/store.py |
05b92658202197d88164d49f6e888b8571ec892e3becd250b58ff975a7c6567d |
| tools/generate_contract_reference.py |
5018e1629d58c65e917e0701eaf9932df49dad003fe3a7ac58a802a77a96525f |