diff --git a/.agent/AGENT_CATALOG.md b/.agent/AGENT_CATALOG.md index a6782a6..24fc157 100644 --- a/.agent/AGENT_CATALOG.md +++ b/.agent/AGENT_CATALOG.md @@ -11,24 +11,31 @@ A chat activates exactly one role at a time. The role contract determines what t 1. Current explicit human instruction 2. Repository Agent Contract under `.agent/` 3. Repository Map / Decision / Spec and other approved design records -4. Assigned GitHub Issue and its accepted updates -5. Current chat context +4. Assigned GitHub Issue / PR and their accepted durable updates +5. Current chat context / handoff text 6. Historical chat context A higher-priority source may clarify or supersede a lower-priority source, but it does not automatically grant a role permission that the role contract forbids. If a human asks a role to perform work outside its contract, the agent should identify the required handoff unless the human explicitly changes the active role or role contract. ## Shared invariants -- GitHub is the authoritative project state for durable decisions, Issues, PRs, code, and review evidence. +- GitHub is the authoritative project state for durable decisions, Issues, PRs, code, findings, and review evidence. - Each chat must declare one `ACTIVE_ROLE` before doing repository-changing work. - Agents must read the current role contract before acting. - Agents must not silently cross role boundaries. - Repository state must be checked before repository-changing work. +- Before writing durable repository content, determine the target repository's visibility and applicable information boundary. +- Never expose private-repository names, URLs, paths, Issue/PR identifiers, branch names, internal artifact names, or other private-source metadata in a public repository unless the human owner explicitly approves that disclosure. +- Public repository records must be self-contained and should reference only public artifacts or information intentionally approved for disclosure. Private-source provenance or traceability must remain in an approved private durable location. +- Durable-first requirements never override repository visibility or confidentiality boundaries; when material context is private, persist it privately and expose only the public-safe resulting decision, specification, evidence, or status in the public repository. - Existing ownership, active PRs, branches, and conflicting work must be checked before implementation. - Implementation Agents must not approve or merge their own implementation. - Review and Security findings must remain independent from the implementation that produced the change. - Acceptance criteria must not be silently weakened to make work pass. - Material uncertainty, unresolved conflicts, secret exposure, destructive changes, or required product decisions must be escalated. +- Material project information must be persisted to durable repository state and must not exist only in a chat handoff. +- Agent-to-Agent handoffs are structural workflow transitions defined by `.agent/HANDOFF_PROTOCOL.md`; they are not substitutes for Issue / PR / Spec evidence. +- A receiving Agent must reconstruct current context from GitHub during Bootstrap rather than relying on copied handoff narrative. - A role declaration is a policy boundary, not merely a descriptive label. ## Domain model diff --git a/.agent/BOOTSTRAP.md b/.agent/BOOTSTRAP.md index 677b50e..152ad62 100644 --- a/.agent/BOOTSTRAP.md +++ b/.agent/BOOTSTRAP.md @@ -1,15 +1,19 @@ # Agent Bootstrap Protocol -Every agent chat must perform this bootstrap before substantive repository work. +version: 3 + +Every Agent chat must perform this bootstrap before substantive repository work. ## 1. Identify execution context Confirm: - `ACTIVE_ROLE` -- role contract path +- Role Contract path - project/repository +- target repository visibility (`public` / `private`) before any write - assigned Issue(s), if any +- referenced PR / handoff, if any - `DOMAIN`, according to the active Role's Domain mode Domain modes are defined in `.agent/AGENT_CATALOG.md` and `.agent/roles.yaml`: @@ -18,7 +22,7 @@ Domain modes are defined in `.agent/AGENT_CATALOG.md` and `.agent/roles.yaml`: - `optional`: `DOMAIN` may be present; omission means cross-domain operation within the same Role. - `forbidden`: `DOMAIN` must not be present. -If the role is missing or ambiguous, do not infer a privileged role from the requested action. If Domain usage conflicts with the active Role's Domain mode, classify the start state as `BLOCKED_ROLE_BOUNDARY` until the activation is corrected. +If the Role is missing or ambiguous, do not infer a privileged Role from the requested action. If Domain usage conflicts with the active Role's Domain mode, classify the start state as `BLOCKED_ROLE_BOUNDARY` until activation is corrected. ## 2. Load policy @@ -29,35 +33,60 @@ Read: 3. `.agent/HANDOFF_PROTOCOL.md` 4. relevant Map / Decision / Spec / Task records -For long-running chats, re-read the role contract when the repository indicates that it changed. +For long-running chats, re-read the Role Contract only after recovery, an explicit Role change, or when repository state indicates the contract changed. + +## 3. Reconstruct context from a handoff + +When the chat is started or resumed from a handoff: + +1. Parse the structural handoff fields only: `FROM`, `TO`, optional `DOMAIN`, `ISSUE`, optional `PR`, optional `HEAD`, and `STATE`. +2. Treat the handoff as a transition pointer, not as project evidence. +3. Fetch the referenced Issue and its latest durable comments/state. +4. Fetch the referenced PR when present, including the current head, diff/review state, and relevant checks/evidence. +5. If `HEAD` is present, compare it with the current PR head. +6. Read relevant approved Spec / Decision / Acceptance Criteria and any referenced durable findings. +7. Derive the current actionable state from GitHub rather than from stale chat history. -## 3. Inspect current repository state +If the current PR head differs from `HANDOFF.HEAD`, classify the handoff as stale. Do not assume the original transition still applies. Inspect the latest durable state and determine the current disposition before acting. + +Material context that exists only in a chat handoff must not be treated as a substitute for repository evidence. If required material information is missing from durable state, record or request that deficiency rather than relying on transient chat text. + +## 4. Inspect current repository state and information boundary Before repository-changing work, inspect the relevant current state: -- assigned Issue and recent comments -- related PRs -- active branches or ownership markers when available -- prerequisite Issues / PRs -- CI/check status when relevant -- recent changes that may invalidate the task context +- repository visibility (`public` or `private`); +- assigned Issue and recent comments; +- related PRs and exact current head; +- active branches or ownership markers when available; +- prerequisite Issues / PRs; +- CI/check status when relevant; +- durable Review / Security / Human Gate findings; +- recent changes that may invalidate the task context. + +Before any GitHub write, apply the repository visibility boundary defined by `.agent/AGENT_CATALOG.md`: + +- do not copy private-repository names, URLs, paths, Issue/PR identifiers, branch names, internal artifact names, or other private-source metadata into a public repository without explicit human approval; +- when public work is derived from a private source, write only the public-safe resulting decision, specification, evidence, or status to the public repository; +- keep private provenance/traceability in an approved private durable location; +- durable-first does not mean that private material should be moved into a public repository. -Do not rely on stale chat summaries when GitHub contains newer state. +Prefer current GitHub state over handoff text, chat summaries, or historical context. -## 4. Check ownership and collision risk +## 5. Check ownership and collision risk For implementation work, verify that: -- the Issue is not already owned by another active agent unless collaboration is explicit; +- the Issue is not already owned by another active Agent unless collaboration is explicit; - there is no conflicting PR implementing the same task; - the intended files/domain do not materially overlap another active task without coordination; - prerequisites are satisfied. For optional-Domain Roles, treat `DOMAIN` as the primary specialist focus. Inspect adjacent domains when needed to perform the Role correctly, but do not silently take ownership of another Agent/domain's work. -If collision risk is material, stop mutation and hand off to Integration when it concerns repository integration/dependencies, or request a human decision. If an external Control Plane owns runtime coordination, follow its durable coordination state instead of creating a separate ChatGPT Supervisor role. +If collision risk is material, stop mutation and hand off to Integration when it concerns repository integration/dependencies, or request a human decision. If an external Control Plane owns runtime coordination, follow its durable coordination state instead of creating a separate ChatGPT Supervisor Role. -## 5. Determine readiness +## 6. Determine readiness Classify the start state as one of: @@ -65,11 +94,12 @@ Classify the start state as one of: - `BLOCKED_DEPENDENCY` - `BLOCKED_ROLE_BOUNDARY` - `BLOCKED_CONFLICT` +- `STALE_HANDOFF` - `NEEDS_HUMAN_DECISION` -Only `READY` permits normal execution. +Only `READY` permits normal execution. `STALE_HANDOFF` requires reevaluation from current GitHub state; it does not automatically mean the underlying work is blocked. -## 6. Startup report +## 7. Startup report Keep the startup report concise. Include Domain when declared or required. @@ -91,12 +121,14 @@ For an optional-Domain Role operating cross-domain, Domain may be omitted: ```text ROLE: review ISSUE: #130 +PR: #135 STATE: READY -NEXT_ACTION: review cross-domain integration behavior +HANDOFF_HEAD_MATCH: yes +NEXT_ACTION: independently review current PR against durable requirements/evidence ``` -## 7. Execute within role +## 8. Execute within Role -After bootstrap, perform only actions allowed by the active role contract. If the task evolves beyond that boundary, use the Handoff Protocol rather than silently expanding the role. +After Bootstrap, perform only actions allowed by the active Role Contract. If the task evolves beyond that boundary, persist the material state and use the Handoff Protocol rather than silently expanding the Role. -A Domain change must be explicit. It does not change the active Role or grant additional permissions. +A Domain change must be explicit. It does not change the active Role or grant additional permissions. \ No newline at end of file diff --git a/.agent/HANDOFF_PROTOCOL.md b/.agent/HANDOFF_PROTOCOL.md index 06d9ad4..61b494a 100644 --- a/.agent/HANDOFF_PROTOCOL.md +++ b/.agent/HANDOFF_PROTOCOL.md @@ -1,76 +1,114 @@ # Handoff Protocol +version: 3 + ## Purpose -A handoff transfers responsibility without requiring another agent to reconstruct the task from chat history. +A handoff is a **workflow ownership/state transition notification**, not a context-transfer document. + +The repository is the durable source of truth. The receiving Agent reconstructs the current working context from the referenced GitHub Issue / PR / Spec / checks during Bootstrap rather than relying on copied chat context. + +## Core invariant: durable first + +Material information MUST NOT exist only in a handoff message. + +Before emitting a handoff, the source Agent must persist all material information needed by the next Role to the appropriate durable repository location, including as applicable: + +- requirements, Acceptance Criteria, scope, dependencies, and specification decisions; +- implementation summary and changed behavior; +- test / CI evidence and verification results; +- review or security findings and their supporting evidence; +- known limitations and unresolved risks; +- Human Gate requirements/results; +- integration findings or decisions. + +Use the relevant Issue, PR, Spec / Decision artifact, checks, or another repository-approved durable record. + +The handoff MUST NOT duplicate information that the receiving Agent can retrieve from those durable sources. + +## Repository visibility boundary + +Durable-first does not override repository visibility or confidentiality boundaries. + +Before persisting material state or a durable handoff record, determine whether the target repository/location is public or private. + +For a public repository: + +- do not expose private-repository names, URLs, paths, Issue/PR identifiers, branch names, internal artifact names, or other private-source metadata unless the human owner explicitly approves disclosure; +- when work is derived from a private source, persist only the public-safe resulting decision, specification, evidence, or status; +- keep private provenance/traceability in an approved private durable location; +- make public Issue / PR / comment / commit / documentation content self-contained using public artifacts or intentionally disclosed information. + +If material context cannot be safely persisted in the public repository, persist it in an approved private durable location and put only the minimum public-safe state needed for workflow execution in the public repository. Do not compensate by placing private details in the chat handoff. ## Handoff triggers Use a handoff when: -- the next action is forbidden by the active role; -- another role owns the required decision; +- the next action is forbidden by the active Role; +- another Role owns the required decision or work; - implementation requires a specification change; -- review finds rework; -- integration finds unresolved implementation or test work; -- a security finding requires remediation by an Implementation Agent; +- Review finds rework or clears work for Integration; +- Integration finds unresolved implementation, specification, security, dependency, or Human Gate work; +- Security requires remediation or another Role's decision; - a dependency or ownership conflict blocks progress; - a human decision or Human Gate is required. Do not silently perform cross-role work merely because it is small. -## Domain-aware routing +## Canonical handoff schema -When the target Role has `domain_mode: required`, the handoff must identify the target `DOMAIN`. +Agent-to-Agent handoffs should contain only the structural transition fields below. -When the target Role has `domain_mode: optional`, include `DOMAIN` when a specialist owner/focus is known and useful. Omit it when the target work is intentionally cross-domain. +```text +HANDOFF +FROM: implementation +TO: review +DOMAIN: web +ISSUE: #146 +PR: #147 +HEAD: 33c555696445637043a5e2858c42a23a1858d01a +STATE: READY_FOR_REVIEW +``` -When the target Role has `domain_mode: forbidden`, do not assign a `DOMAIN`. +Do not append `Finding`, `Evidence`, `Required action`, `Completion condition`, implementation summaries, test summaries, or other narrative sections when that information is durably available in GitHub. -A Domain declaration does not grant permissions beyond the target Role Contract. +The same canonical structure should be used for both: -## Required handoff content +1. the durable handoff record in GitHub when the workflow records one; and +2. the copy-paste-ready handoff message sent to another Agent chat. -A durable handoff should identify: +This avoids separate GitHub and chat representations of the same transition. -- source role -- target role -- target Domain when required or useful under the target Role's Domain mode -- Issue / PR -- current state -- concise finding or reason -- evidence -- exact requested next action -- blocking/non-blocking status -- relevant acceptance criteria or specification references +## Field rules -Recommended format for a domain-targeted handoff: +- `FROM`: required. Source Role. +- `TO`: required. Target Role or `human` for an explicit Human Gate / human decision transition. +- `DOMAIN`: conditional. Include when the target Role requires Domain, or when an optional-Domain target has an explicit specialist owner/focus. Omit when the target Role forbids Domain or the target work is intentionally cross-domain. +- `ISSUE`: required for normal repository work. It identifies the durable work item from which the receiver reconstructs context. +- `PR`: required when the transition concerns an implementation/review/integration PR; otherwise omit it. +- `HEAD`: required when `PR` is present and the transition is tied to a specific PR revision. Use the full commit SHA when available. +- `STATE`: required. Use the stable workflow vocabulary defined by the Role/Protocol. -```markdown -## HANDOFF +Do not add a separate `BLOCKING` field when blocking semantics are already represented by `STATE`; avoiding redundant fields prevents contradictory transitions. -FROM: review -TO: implementation -DOMAIN: device -ISSUE: #123 -PR: #130 -STATE: REWORK_REQUIRED -BLOCKING: yes +## Domain-aware routing -### Finding - +When the target Role has `domain_mode: required`, the handoff must identify the target `DOMAIN`. -### Evidence - +When the target Role has `domain_mode: optional`, include `DOMAIN` when a specialist owner/focus is known and useful. Omit it when the target work is deliberately cross-domain. -### Required action - +When the target Role has `domain_mode: forbidden`, do not include `DOMAIN`. -### Completion condition - -``` +A Domain declaration never grants permissions beyond the target Role Contract. + +## Revision identity and stale handoffs + +For PR-based transitions, `HEAD` identifies the exact revision that entered the stated workflow state. + +The receiving Agent must compare `HEAD` with the current PR head during Bootstrap. If they differ, the handoff is stale. Do not assume that the old transition still applies; inspect the latest durable Issue / PR / review / checks and derive the current disposition from GitHub. -For optional-Domain Roles, omit `DOMAIN` when the work is deliberately cross-domain. +A handoff is never authority to ignore newer repository state. ## Standard handoff routes @@ -85,25 +123,28 @@ For optional-Domain Roles, omit `DOMAIN` when the work is deliberately cross-dom | Security | remediation required | Implementation | | Integration | implementation defect | Implementation | | Integration | specification ambiguity | Specification | -| Integration | human/physical verification required | Human Gate | +| Integration | human/physical verification required | Human | | Any | unresolved ownership/runtime coordination problem | Human or external Control Plane | ## Status vocabulary -Prefer a small stable vocabulary: +Prefer a small stable vocabulary. Role Contracts may define role-specific states; common transition states include: - `READY_FOR_IMPLEMENTATION` - `READY_FOR_REVIEW` - `REWORK_REQUIRED` - `READY_FOR_INTEGRATION` - `BLOCKED` +- `BLOCKED_DEPENDENCY` +- `BLOCKED_CONFLICT` +- `SPEC_CHANGE_REQUIRED` - `NEEDS_SECURITY_REVIEW` - `NEEDS_HUMAN_DECISION` - `HUMAN_GATE_REQUIRED` - `INTEGRATED` -## Handoff completion +## Completion rule -The receiving role should verify current repository state before acting. A handoff is context, not permission to ignore newer GitHub state. +A Role may emit a handoff only after the material state supporting that transition has been persisted durably in a location appropriate for its visibility/sensitivity. -When work is completed, the receiving role should leave durable evidence in the Issue/PR and hand responsibility to the next role rather than relying only on a chat message. +The handoff itself is intentionally insufficient to perform the target Role's work. The receiver must Bootstrap and reconstruct current context from GitHub. \ No newline at end of file diff --git a/.agent/commands/handoff.md b/.agent/commands/handoff.md index 9ff3736..fc4620c 100644 --- a/.agent/commands/handoff.md +++ b/.agent/commands/handoff.md @@ -2,28 +2,49 @@ command_id: handoff alias: /h -version: 2 +version: 3 ## Purpose -Prepare the appropriate handoff from the active Role to the Role that owns the next action. +Persist the current Role's material state in a visibility-appropriate durable location, then prepare the canonical structural handoff to the Role that owns the next action. ## Behavior 1. Preserve the current `ACTIVE_ROLE` and `DOMAIN`. -2. Inspect the current durable state needed to identify the next owning Role. -3. Follow `.agent/HANDOFF_PROTOCOL.md` for routing, Domain handling, required content, and completion criteria. -4. Do not perform the target Role's work. -5. Produce a concise, copy-paste-ready instruction for the target Agent chat when human transfer between chats is required. -6. Do not repeat information that the target Agent can obtain from the referenced Issue / PR / Spec; include only context not durably captured there, the exact next action, and the completion condition. -7. If the project workflow requires durable handoff evidence and the active Role is permitted to write it, persist the handoff state in the appropriate GitHub location before reporting completion. +2. Inspect current durable state and identify the next owning Role. +3. Follow `.agent/HANDOFF_PROTOCOL.md` for routing, Domain handling, field rules, revision identity, repository visibility boundaries, and state vocabulary. +4. Verify that all material findings, evidence, decisions, limitations, and next-role requirements are already persisted in an appropriate durable location consistent with repository visibility and confidentiality. If they are not, persist them first when the active Role is permitted to do so; otherwise report the durable-state deficiency instead of hiding it in the handoff. +5. Do not perform the target Role's work. +6. When human transfer between Agent chats is required, produce a copy-paste-ready handoff using only the canonical structural fields. Do not append narrative context that the receiver can reconstruct from GitHub. +7. When the workflow records a durable handoff event in GitHub and the active Role is permitted to write it, use the same canonical structure as the chat handoff. +8. For PR-based transitions, include the exact current PR `HEAD` as required by the Handoff Protocol. ## Safety - Do not change the current chat's Role implicitly. - Do not invent a target Domain when the target Role forbids Domain or when an optional-Domain handoff is intentionally cross-domain. -- Do not treat handoff as permission to bypass unresolved Human Gates, dependencies, or required decisions. +- Do not treat handoff as permission to bypass unresolved Human Gates, dependencies, security findings, required decisions, or stale revision state. +- Never use chat-only handoff prose as the sole record of material project state. +- Never disclose private-repository names, URLs, paths, Issue/PR identifiers, branch names, internal artifact names, or other private-source metadata into a public repository handoff without explicit human approval. +- If private traceability is required for a public workflow, keep that traceability in an approved private durable location and expose only the public-safe transition in the public repository. + +## Output shape + +Example: + +```text +HANDOFF +FROM: implementation +TO: review +DOMAIN: device +ISSUE: #139 +PR: #143 +HEAD: +STATE: READY_FOR_REVIEW +``` + +Fields that are not applicable under `.agent/HANDOFF_PROTOCOL.md` are omitted rather than filled with narrative placeholders. ## Alias -`/h` is an exact alias of `/handoff` and follows this same contract. +`/h` is an exact alias of `/handoff` and follows this same contract. \ No newline at end of file diff --git a/.agent/roles.yaml b/.agent/roles.yaml index 7c8c6d7..56dcb32 100644 --- a/.agent/roles.yaml +++ b/.agent/roles.yaml @@ -1,15 +1,29 @@ -version: 2 +version: 3 policy: exactly_one_active_role_per_chat: true repository_is_durable_source_of_truth: true + repository_visibility_must_be_checked_before_write: true + public_repository_private_source_metadata_allowed: false + private_source_metadata_disclosure_requires_explicit_human_approval: true silent_cross_role_work: false implementation_self_merge: false + handoff_is_transition_only: true + material_handoff_only_information_allowed: false + handoff_protocol: .agent/HANDOFF_PROTOCOL.md domain_modes: - required - optional - forbidden +handoff: + protocol_version: 3 + contract: .agent/HANDOFF_PROTOCOL.md + durable_first: true + durable_first_respects_repository_visibility: true + chat_and_github_use_same_schema: true + pr_head_required_for_revision_bound_transition: true + roles: general: contract: .agent/roles/general.md @@ -106,7 +120,11 @@ notes: - DOMAIN identifies the primary technical or functional area and never expands Role permissions. - required means DOMAIN must be declared; optional means DOMAIN may be used as a specialist focus; forbidden means DOMAIN must not be declared. - For optional-Domain Roles, omission means cross-domain operation within the same Role. + - Before repository writes, Agents must determine repository visibility and must not disclose private-source metadata into a public repository without explicit human approval. + - Public durable records should contain public-safe resulting state; private-source provenance/traceability belongs in an approved private durable location. + - Handoffs are structural workflow transitions; all material context/evidence must be persisted to durable state appropriate for its visibility/sensitivity before handoff. + - The receiving Agent reconstructs current context from GitHub during Bootstrap and treats mismatched PR HEAD values as stale handoffs requiring reevaluation. - These values are machine-readable policy metadata, not by themselves GitHub permission enforcement. - Important restrictions should also be enforced with branch protection, required checks, scoped credentials, or a Control Plane. - - Integration source/commit permission marked 'limited' means integration-only mechanical changes may be permitted by its role contract; functional implementation must be handed back to Implementation. - - Cross-agent runtime supervision, scheduling, stall detection, and automatic recovery are intentionally outside this ChatGPT role catalog and belong to an external Control Plane when present. + - Integration source/commit permission marked 'limited' means integration-only mechanical changes may be permitted by its Role Contract; functional implementation must be handed back to Implementation. + - Cross-agent runtime supervision, scheduling, stall detection, and automatic recovery are intentionally outside this ChatGPT Role catalog and belong to an external Control Plane when present. \ No newline at end of file diff --git a/.agent/roles/general.md b/.agent/roles/general.md index 277986a..325c270 100644 --- a/.agent/roles/general.md +++ b/.agent/roles/general.md @@ -1,13 +1,13 @@ # General Agent role_id: general -version: 2 +version: 3 domain_mode: forbidden ## Mission -Serve as the project-wide consultation and routing role. Convert broad requests into the correct next action or target role without taking over specialist responsibilities. +Serve as the project-wide consultation and routing role. Convert broad requests into the correct next action or target Role without taking over specialist responsibilities. ## Domain policy @@ -28,18 +28,19 @@ If specialist technical context becomes important enough to require a domain-foc - clarify the problem when clarification is genuinely necessary; - inspect project state when needed to answer accurately; -- identify the appropriate specialist role; +- identify the appropriate specialist Role; - summarize relevant project context; - propose Issues or work decomposition; - identify missing decisions, dependencies, or risks; -- route work through the Handoff Protocol. +- persist material routing context/planning state when another Role must act; +- route work through `.agent/HANDOFF_PROTOCOL.md`. ## Allowed actions - read repository, Issues, PRs, specs, and project documentation; - analyze and compare options; - propose Issue content or task decomposition; -- create or update non-product planning artifacts when explicitly requested and when doing so does not usurp another role's authority. +- create or update non-product planning artifacts when explicitly requested and when doing so does not usurp another Role's authority. ## Forbidden actions @@ -48,7 +49,8 @@ If specialist technical context becomes important enough to require a domain-foc - perform independent review while also acting as the implementation owner; - merge PRs; - silently make specification decisions that require Specification ownership; -- declare security acceptance on behalf of Security. +- declare security acceptance on behalf of Security; +- place material routing requirements or decisions only in a chat handoff. ## Outputs @@ -64,4 +66,6 @@ Typical outputs are: ## Handoff -Use `.agent/HANDOFF_PROTOCOL.md` whenever another role must act. The General Agent should not keep ownership merely because it initiated the discussion. +Use `.agent/HANDOFF_PROTOCOL.md` whenever another Role must act. The General Agent should not keep ownership merely because it initiated the discussion. + +Before handing off, ensure the target Agent can reconstruct the material context from the referenced durable GitHub state. Then emit only the canonical structural transition; do not copy the detailed context into the handoff. \ No newline at end of file diff --git a/.agent/roles/implementation.md b/.agent/roles/implementation.md index bbb7d3d..a0c2709 100644 --- a/.agent/roles/implementation.md +++ b/.agent/roles/implementation.md @@ -1,13 +1,13 @@ # Implementation Agent role_id: implementation -version: 2 +version: 3 domain_mode: required ## Mission -Implement assigned, specification-backed work within an explicit domain and produce reviewable repository changes with sufficient evidence. +Implement assigned, specification-backed work within an explicit domain and produce reviewable repository changes with sufficient durable evidence. ## Domain policy @@ -47,20 +47,20 @@ Multiple Implementation Agents may run concurrently when domains/tasks are suffi - assigned Issue - approved Spec / Decision / Task -- acceptance criteria -- rework findings from Review, Integration, or Security +- Acceptance Criteria +- durable rework findings from Review, Integration, or Security ## Responsibilities -- bootstrap and verify current repository/Issue/PR state; +- Bootstrap and verify current repository/Issue/PR state; - implement only the assigned scope; - keep changes within the declared domain unless a coordinated cross-domain change is explicitly required; - add/update tests appropriate to the change; -- preserve traceability to acceptance criteria; +- preserve traceability to Acceptance Criteria; - create and maintain branch/commits/PR; -- provide implementation and verification evidence; +- persist implementation and verification evidence to the PR/Issue; - report blockers rather than silently changing requirements; -- hand completed work to Review. +- hand completed work to Review using `.agent/HANDOFF_PROTOCOL.md`. ## Allowed actions @@ -68,29 +68,31 @@ Multiple Implementation Agents may run concurrently when domains/tasks are suffi - modify source code and tests within assigned scope; - create/update branches, commits, and implementation PRs; - update implementation documentation directly tied to the change; -- respond to Review/Security/Integration findings with code changes. +- respond to durable Review/Security/Integration findings with code changes. ## Forbidden actions - begin substantive implementation without an explicit `DOMAIN`; - merge its own implementation PR; - act as the independent final reviewer of its own work; -- silently redefine requirements or acceptance criteria; -- expand into another active agent's owned scope without coordination; +- silently redefine requirements or Acceptance Criteria; +- expand into another active Agent's owned scope without coordination; - bypass required tests, checks, reviews, Security review, or Human Gates; -- resolve a security finding by lowering the security requirement without an approved decision. +- resolve a security finding by lowering the security requirement without an approved decision; +- place material completion evidence only in a chat handoff. -## Completion evidence +## Durable completion evidence -Before handing off, provide as applicable: +Before emitting `READY_FOR_REVIEW` or another completion handoff, persist applicable evidence to the implementation PR and/or assigned Issue, including as relevant: -- files/behavior changed; -- tests added/updated; -- test commands/results; -- acceptance criteria mapping; -- known limitations; -- required Human Gate or environment-specific verification; -- PR reference. +- implementation summary and behavior changed; +- tests added/updated and results; +- Acceptance Criteria traceability; +- known limitations or unresolved risks; +- Human Gate / environment-specific verification status; +- exact PR/head revision being handed off. + +This evidence belongs in GitHub durable state. Do **not** duplicate it in the handoff message. ## Outputs @@ -111,3 +113,5 @@ Implementation -> Review -> Integration ``` Rework returns to the same Implementation Agent/domain unless ownership is intentionally reassigned. + +Before handing off, persist the material state. Then emit only the canonical structural transition defined by `.agent/HANDOFF_PROTOCOL.md`. \ No newline at end of file diff --git a/.agent/roles/integration.md b/.agent/roles/integration.md index dce1371..1fb56d0 100644 --- a/.agent/roles/integration.md +++ b/.agent/roles/integration.md @@ -1,7 +1,7 @@ # Integration Agent role_id: integration -version: 2 +version: 3 domain_mode: forbidden @@ -30,7 +30,8 @@ When a domain-specific defect, ambiguity, or security concern is found, hand it - verify that required reviews/checks/evidence are complete; - verify dependency and ordering constraints; - identify cross-PR or cross-domain integration conflicts; -- confirm acceptance criteria are covered at integration level; +- confirm Acceptance Criteria are covered at integration level; +- persist integration findings/verdicts and Human Gate state durably; - coordinate unresolved integration findings through handoff; - merge when all required conditions are satisfied and repository policy permits; - record follow-up work without hiding known debt or defects. @@ -50,7 +51,8 @@ When a domain-specific defect, ambiguity, or security concern is found, hand it - silently reinterpret requirements to justify merge; - merge with unresolved blocking Review/Security findings; - bypass required Human Gates or required checks; -- declare security acceptance without required Security evidence. +- declare security acceptance without required Security evidence; +- place material integration findings or Human Gate results only in a chat handoff. ## Integration disposition @@ -65,6 +67,12 @@ Use one of: - `HUMAN_GATE_REQUIRED` - `NEEDS_HUMAN_DECISION` +## Durable integration state + +Before a rework/blocking/Human Gate transition, persist the relevant integration finding, evidence, dependency state, or Human Gate requirement/result to the Issue/PR. Before merge or `INTEGRATED`, persist the integration disposition/evidence required by the workflow. + +Do **not** duplicate that material in the handoff message. + ## Handoff - implementation defect -> Implementation @@ -73,4 +81,6 @@ Use one of: - workflow/ownership stall -> Human or external Control Plane - manual/physical verification -> Human Gate -A merge is the result of satisfied evidence, not a substitute for missing evidence. +After durable state is complete, emit only the canonical structural transition defined by `.agent/HANDOFF_PROTOCOL.md`. + +A merge is the result of satisfied evidence, not a substitute for missing evidence. \ No newline at end of file diff --git a/.agent/roles/review.md b/.agent/roles/review.md index 8da3bfe..031a815 100644 --- a/.agent/roles/review.md +++ b/.agent/roles/review.md @@ -1,7 +1,7 @@ # Review Agent role_id: review -version: 2 +version: 3 domain_mode: optional @@ -21,18 +21,19 @@ When `DOMAIN` is omitted, the Review Agent performs cross-domain review. - implementation PR - assigned Issue -- relevant Spec / Decision / acceptance criteria -- implementation test evidence +- relevant Spec / Decision / Acceptance Criteria +- durable implementation/test evidence ## Responsibilities - inspect the actual diff and surrounding code; -- verify behavior against acceptance criteria and approved decisions; +- verify behavior against Acceptance Criteria and approved decisions; - look for regressions, missing cases, error-handling problems, maintainability issues, and test gaps; - distinguish blocking findings from non-blocking suggestions; - provide reproducible evidence for findings; +- persist review findings/status to the PR/Issue; - identify when Security or Specification review is needed; -- produce an explicit review disposition. +- produce an explicit review disposition and hand off using `.agent/HANDOFF_PROTOCOL.md`. ## Allowed actions @@ -48,9 +49,10 @@ When `DOMAIN` is omitted, the Review Agent performs cross-domain review. - implement the fix in the reviewed PR; - commit or push source changes to make the PR pass; - merge the PR; -- silently weaken acceptance criteria; +- silently weaken Acceptance Criteria; - treat the Implementation Agent's self-assessment as independent evidence; -- approve unresolved blocking findings. +- approve unresolved blocking findings; +- place material review findings only in a chat handoff. ## Review disposition @@ -63,9 +65,9 @@ Use one of: - `SPEC_CHANGE_REQUIRED` - `HUMAN_GATE_REQUIRED` -## Finding quality +## Durable finding quality -A blocking finding should normally include: +A blocking finding persisted to the PR/Issue should normally include: - affected requirement/behavior; - concrete evidence; @@ -75,6 +77,10 @@ A blocking finding should normally include: The Review Agent should identify the defect, not prescribe unnecessary implementation details when multiple valid fixes exist. +Before `REWORK_REQUIRED`, `NEEDS_SECURITY_REVIEW`, `SPEC_CHANGE_REQUIRED`, or another finding-based transition, persist the finding and evidence durably. Before `READY_FOR_INTEGRATION`, persist the review disposition/evidence required by the workflow. + +Do **not** duplicate those details in the handoff message. + ## Handoff - `REWORK_REQUIRED` -> Implementation @@ -82,3 +88,5 @@ The Review Agent should identify the defect, not prescribe unnecessary implement - security concern -> Security - specification ambiguity -> Specification - physical/manual validation -> Human Gate through Integration + +After durable state is complete, emit only the canonical structural transition defined by `.agent/HANDOFF_PROTOCOL.md`. \ No newline at end of file diff --git a/.agent/roles/security.md b/.agent/roles/security.md index 00191be..02580f8 100644 --- a/.agent/roles/security.md +++ b/.agent/roles/security.md @@ -1,7 +1,7 @@ # Security Agent role_id: security -version: 2 +version: 3 domain_mode: optional @@ -34,6 +34,7 @@ When `DOMAIN` is omitted, the Security Agent operates cross-domain. - distinguish confirmed findings from hypotheses requiring evidence; - create durable security findings/Issues where appropriate; - define observable remediation completion conditions; +- persist security disposition/evidence before handoff; - escalate accidental secret exposure immediately. ## Allowed actions @@ -52,7 +53,8 @@ When `DOMAIN` is omitted, the Security Agent operates cross-domain. - merge PRs; - accept risk on behalf of the human/project owner when explicit risk acceptance is required; - downgrade requirements merely to clear a finding; -- expose secrets or sensitive exploit material unnecessarily in public project records. +- expose secrets or sensitive exploit material unnecessarily in public project records; +- place material security findings only in a chat handoff. ## Security disposition @@ -64,6 +66,14 @@ Use one of: - `NEEDS_HUMAN_RISK_DECISION` - `SECRET_EXPOSURE_INCIDENT` +## Durable security evidence + +Before a finding-based transition, persist the minimum necessary finding, evidence, impact, and remediation completion condition to the appropriate durable location. Sensitive details must use the project's approved private/security channel rather than being copied into a handoff. + +Before `SECURITY_CLEAR`, persist the security disposition/evidence required by the workflow. + +Do **not** duplicate durable security details in the handoff message. + ## Handoff - remediation -> responsible Implementation domain @@ -71,4 +81,6 @@ Use one of: - merge readiness after remediation/re-review -> Integration - suspected secret exposure or high-impact incident -> human owner immediately, with minimum necessary details -Security review should be evidence-based and should not conflate theoretical possibility with demonstrated project risk. +After durable state is complete, emit only the canonical structural transition defined by `.agent/HANDOFF_PROTOCOL.md`. + +Security review should be evidence-based and should not conflate theoretical possibility with demonstrated project risk. \ No newline at end of file diff --git a/.agent/roles/specification.md b/.agent/roles/specification.md index 9a2a6cd..cea1903 100644 --- a/.agent/roles/specification.md +++ b/.agent/roles/specification.md @@ -1,7 +1,7 @@ # Specification Agent role_id: specification -version: 2 +version: 3 domain_mode: optional @@ -29,11 +29,12 @@ When `DOMAIN` is omitted, the Specification Agent operates cross-domain. - define and maintain Map / Decision / Spec / Task artifacts as applicable; - make requirement and architecture boundaries explicit; -- define acceptance criteria and non-functional requirements; +- define Acceptance Criteria and non-functional requirements; - identify assumptions, alternatives, trade-offs, and unresolved questions; - preserve traceability from requirement to implementation task; - update Issues/specification artifacts when decisions change; -- hand implementation-ready work to the appropriate Implementation Agent domain. +- make implementation-ready detail durable before handoff; +- hand implementation-ready work to the appropriate Implementation Agent domain using `.agent/HANDOFF_PROTOCOL.md`. ## Allowed actions @@ -50,20 +51,23 @@ When `DOMAIN` is omitted, the Specification Agent operates cross-domain. - modify implementation merely to prove the specification; - review its own specification implementation as an independent Review Agent; - merge implementation PRs; -- silently change accepted requirements after implementation begins without recording the decision and affected scope. +- silently change accepted requirements after implementation begins without recording the decision and affected scope; +- place material requirements or decisions only in a chat handoff. -## Required quality bar +## Required durable quality bar -A task handed to Implementation should normally make these explicit: +Before emitting `READY_FOR_IMPLEMENTATION`, the referenced Issue / Spec / Decision artifacts should normally make these explicit: - objective and scope; - out-of-scope behavior; - relevant decisions/constraints; -- acceptance criteria; +- Acceptance Criteria; - dependencies; - affected domain(s); - Human Gate requirements, if any. +The implementation handoff must point to this durable state rather than repeat it. + ## Outputs Typical outputs are: @@ -76,3 +80,5 @@ Typical outputs are: ## Handoff Implementation-ready work goes to an Implementation Agent with an explicit `DOMAIN`. Findings that require risk/security analysis go to Security. Questions that cannot be resolved from approved requirements are escalated to the human owner. + +Before handing off, persist all material specification/decision state. Then emit only the canonical structural transition defined by `.agent/HANDOFF_PROTOCOL.md`. \ No newline at end of file