Clarify orchestrator role boundary

Author: Mikhail Orlov

AGENTS.md

@@ -31,42 +31,54 @@ If docs are stale or missing for the requested work, refresh `docs_project/` fir
 
 ## Agent Roles
 
+### Architect
+
+- Creates or updates one `specs/<feature-id>/` folder for each repository-changing user request before implementation begins.
+- Owns `spec.md`, `plan.md`, and `tasks.md` creation and updates for the assigned feature memory.
+- Ensures feature memory names goal, scope, acceptance criteria, negative scenario, and verification evidence.
+- Splits independent goals into separate feature folders instead of bundling unrelated changes into one process record.
+- Hands complete feature memory to the Orchestrator for coordination and enforcement.
+
 ### Orchestrator
 
 - Reads repository memory before starting.
-- Creates or updates feature memory before product-code changes.
-- Ensures feature memory names goal, scope, acceptance criteria, negative scenario, and verification evidence.
-- Slices work into one branch and one PR per task.
-- Keeps docs, specs, and PR state aligned.
+- Coordinates assigned agents and enforces the repository workflow.
+- Confirms each repository-changing user request has its own Architect-owned `specs/<feature-id>/` folder before implementation starts.
+- Slices work into one branch and one PR per task, then delegates repository file changes to assigned agents.
+- Keeps docs, specs, and PR state aligned through coordination and verification.
+- Must not directly edit repository files, including code, docs, specs, workflow files, or scripts.
 - Does not declare completion until the PR is merge-ready.
 
 ### Implementation Agent
 
+- Starts from assigned feature memory and does not begin implementation if `spec.md`, `plan.md`, or `tasks.md` is missing.
 - Works only from an assigned isolated worktree.
 - Stays within one branch and one PR per task slice.
-- Updates `specs/<feature-id>/tasks.md` in the same PR.
+- Keeps `specs/<feature-id>/tasks.md` current in the same PR.
 - Records dead ends, decisions, and known issues in the active feature memory.
 - Updates durable docs when behavior, architecture, workflows, or deploy rules change.
 - Never merges directly to the default branch.
 
 ### Review Agent
 
 - Reviews pull request diffs for bugs, regressions, missing tests, and contract violations.
+- Checks that repository-changing work has complete feature memory and follows Architect, Orchestrator, Implementation Agent, and Review Agent role boundaries.
 - Does not implement unrelated features during review.
 - Emits review output in the configured backend format.
 
 ## Agent Boundaries
 
 - One worker equals one worktree.
 - One implementation loop equals one branch and one PR.
-- Product-code PRs require complete feature memory: `spec.md`, `plan.md`, and `tasks.md`.
+- Every repository-changing user request must be represented by its own `specs/<feature-id>/` folder before implementation.
+- Repository-changing PRs require complete feature memory: `spec.md`, `plan.md`, and `tasks.md`.
 - Acceptance criteria must be verified with evidence, not only an AI-written summary.
 - `docs_project/`, `.specify/`, `specs/`, and `docs/specify/` are durable memory, not disposable session notes.
 - Do not edit secrets or production resources directly.
 
 ## Delivery Workflow
 
-- Product changes land through pull requests; do not push directly to `main`.
+- Repository-changing work lands through pull requests; do not push directly to `main`.
 - Required checks for this repository are defined in `.unicorn-hub/config.json` (`requiredChecks`) and applied to branch protection via `scripts/apply-branch-protection.mjs`.
 - Run local preflight before pushing.
 - Follow the Docker-only contract for runtime-affecting work (`make build`, `make up`, `make down`) once runtime scaffolding is present.

specs/002-orchestrator-role-boundary/plan.md

@@ -0,0 +1,64 @@
+# Plan: Orchestrator Role Boundary
+
+## Summary
+
+Update Cabadrive durable agent instructions so the repository workflow reflects the corrected division of responsibility: Architect creates feature memory for each request, Orchestrator coordinates and enforces the flow, Implementation Agents implement from assigned memory, and Review Agents verify compliance.
+
+This feature is intentionally documentation/process scoped. It does not alter product code, runtime behavior, CI workflows, or repository automation scripts.
+
+## Technical Context
+
+- runtime: none; process documentation only.
+- dependencies: none.
+- product paths: none.
+- expected documentation paths: `AGENTS.md` and any other durable agent-rule files that repeat the old Orchestrator ownership model.
+- feature memory path: `specs/002-orchestrator-role-boundary/`.
+
+## Scope Boundaries
+
+- in scope: role definitions, request intake flow, feature-memory ownership, process acceptance criteria, review expectations.
+- out of scope: product UI, content pipeline, Docker runtime scaffold, CI/workflow script changes, branch-protection logic, automated enforcement.
+
+## Constitution Check
+
+- Spec-first: yes; this feature memory is created before repository-rule edits.
+- Testable boundaries: yes; verification is a constrained diff review plus text checks for old/new role language.
+- Test-first bias: not applicable to executable tests because this is documentation-only; verification will use reviewable textual evidence.
+- Supervised verification: yes; acceptance criteria map to explicit documentation checks.
+- PR-only: yes; implementation should land through a branch and PR.
+- One worktree per task: yes; implementation should happen in the assigned worktree only.
+- Deployability: neutral; no runtime behavior changes.
+- Simplicity: yes; no new tooling or abstractions.
+- Process memory: yes; decisions and known issues are recorded in `tasks.md`.
+
+## Implementation Approach
+
+1. Review current durable agent instructions for statements assigning feature-memory creation to the Orchestrator.
+2. Update role descriptions to introduce or clarify the Architect role.
+3. Update request intake guidance so every repository-changing request is routed to a separate `specs/<feature-id>/` folder before implementation.
+4. Update Implementation Agent and Review Agent guidance only where needed to preserve handoff and compliance expectations.
+5. Confirm the diff does not touch product code, workflow scripts, runtime files, or CI automation.
+
+## Verification
+
+| Acceptance criterion | Planned evidence |
+| --- | --- |
+| AC-001 | Text review shows the Orchestrator role says coordination/enforcement only and no direct repository edits. |
+| AC-002 | Text review shows new request guidance requires a separate `specs/<feature-id>/` folder before implementation. |
+| AC-003 | Text review shows the Architect role owns creation or update of `spec.md`, `plan.md`, and `tasks.md`. |
+| AC-004 | Text review shows Implementation Agent guidance starts from assigned feature memory. |
+| AC-005 | Text review shows Review Agent guidance can verify role-boundary and feature-memory compliance. |
+| AC-006 | `git diff --name-only` for the implementation PR contains only process documentation and `specs/002-orchestrator-role-boundary/` files. |
+
+Negative scenario evidence:
+
+- Search output confirms no remaining durable instruction says the Orchestrator creates or updates feature memory.
+- Search output confirms missing feature memory is treated as a blocker before implementation.
+
+## Risks
+
+- Risk: multiple durable docs may repeat the old role model.
+- Mitigation: search for `Orchestrator`, `feature memory`, `feature-memory`, `spec.md`, `plan.md`, and `tasks.md` before finalizing the documentation update.
+
+- Risk: "every request" could be interpreted too broadly for read-only questions.
+- Mitigation: document the assumption that the rule applies to repository-changing requests; read-only discussion can remain outside implementation flow unless it becomes a change request.

specs/002-orchestrator-role-boundary/spec.md

@@ -0,0 +1,73 @@
+# Spec: Orchestrator Role Boundary
+
+## Goal
+
+Clarify Cabadrive repository agent instructions so every user request starts as a separate feature under `specs/`, the Architect owns feature-memory creation, and the Orchestrator coordinates subagents and enforces workflow without directly editing repository files.
+
+## Scope
+
+In scope:
+
+- Update durable repository agent instructions and rules that define agent roles and request intake flow.
+- Make the Orchestrator boundary explicit: coordination, assignment, sequencing, and enforcement only.
+- Make the Architect responsibility explicit: create or update feature memory before any implementation work.
+- Require each user request to map to its own `specs/<feature-id>/` folder with `spec.md`, `plan.md`, and `tasks.md` before implementation.
+- Preserve implementation and review responsibilities for their respective agents.
+
+Out of scope:
+
+- Product code changes.
+- Workflow script changes.
+- CI, branch-protection, or automation behavior changes.
+- Runtime scaffold, Docker contract, or app feature implementation.
+
+## User Stories
+
+### User Story 1
+
+As a project owner, I want every request captured as a separate feature memory folder before work starts, so that no implementation begins from ad hoc session context.
+
+### User Story 2
+
+As an Orchestrator, I want my role boundary to be explicit, so that I coordinate assigned agents and enforce repository process without directly editing docs, code, or workflow files.
+
+### User Story 3
+
+As an Architect, I want feature-memory ownership documented, so that I can create the spec, plan, and task checklist required before implementation agents begin work.
+
+## Acceptance Criteria
+
+1. Given repository agent instructions, when an agent reads the Orchestrator role, then the Orchestrator is described as a coordinator/enforcer that does not directly edit repository files.
+2. Given a new user request, when repository workflow guidance is followed, then the request is represented by a separate `specs/<feature-id>/` folder before implementation starts.
+3. Given feature-memory guidance, when an Architect role is used, then the Architect is explicitly responsible for creating or updating `spec.md`, `plan.md`, and `tasks.md`.
+4. Given implementation guidance, when an Implementation Agent starts work, then it is instructed to work from assigned feature memory rather than creating the request-level memory itself.
+5. Given review guidance, when a Review Agent checks a PR, then it can verify that role boundaries and feature-memory requirements were followed.
+6. Given this process-rule feature, when the change is implemented, then no product code, workflow scripts, CI automation, or runtime files are modified.
+
+## Negative Scenarios
+
+1. Given an Orchestrator receives a user request, when no feature memory exists, then the Orchestrator must route the request to Architect work instead of directly editing files.
+2. Given a request touches multiple independent goals, when feature memory is created, then the goals must be split into separate feature folders rather than bundled into one vague process record.
+3. Given an Implementation Agent is assigned work, when `spec.md`, `plan.md`, or `tasks.md` is missing, then implementation must not begin.
+
+## Requirements
+
+- FR-001: Agent instructions must state that every user request becomes a separate feature under `specs/` before implementation.
+- FR-002: Agent instructions must define an Architect role responsible for feature-memory creation and updates.
+- FR-003: Agent instructions must define the Orchestrator as responsible for coordinating agents, enforcing flow, and keeping PR/process state aligned.
+- FR-004: Agent instructions must state that the Orchestrator must not directly edit code, docs, specs, workflow files, or scripts.
+- FR-005: Implementation Agent instructions must refer to assigned feature memory as input and keep `tasks.md` current during implementation.
+- FR-006: Review Agent instructions must include checking role-boundary compliance for process-rule changes.
+- FR-007: The feature implementation must avoid product-code and workflow-script changes.
+
+## Success Criteria
+
+- SC-001: The updated durable instructions remove or replace any statement that says the Orchestrator creates or updates feature memory.
+- SC-002: The updated durable instructions identify Architect-owned feature memory as the required first step for every request.
+- SC-003: The feature PR diff is limited to agent/process documentation and this feature memory.
+
+## Assumptions
+
+- "Every request" means every repository-changing request, including process-rule changes, documentation changes, product changes, and workflow changes.
+- The Orchestrator may request or coordinate edits through assigned agents, but does not perform direct repository edits itself.
+- This change is governance/process documentation only; executable enforcement can be considered in a later feature if needed.

specs/002-orchestrator-role-boundary/tasks.md

@@ -0,0 +1,57 @@
+# Tasks: Orchestrator Role Boundary
+
+## Setup
+
+- [x] T001 Create feature memory folder for this process-rule change.
+- [x] T002 Record goal, scope, acceptance criteria, negative scenarios, and verification plan.
+- [x] T003 Confirm implementation branch/worktree before editing durable agent instructions.
+
+## Implementation
+
+- [x] T004 Search durable docs for old Orchestrator ownership language.
+- [x] T005 Update agent role instructions so the Architect owns feature-memory creation.
+- [x] T006 Update Orchestrator instructions so the role is coordination and enforcement only, with no direct repository edits.
+- [x] T007 Update request intake guidance so each repository-changing request maps to a separate `specs/<feature-id>/` folder before implementation.
+- [x] T008 Update Implementation Agent handoff language to start from assigned feature memory.
+- [x] T009 Update Review Agent guidance to check feature-memory and role-boundary compliance.
+
+## Verification
+
+- [x] T010 Verify no product code, workflow scripts, runtime files, CI files, or automation scripts changed.
+- [x] T011 Verify no durable instruction still says the Orchestrator creates or updates feature memory.
+- [x] T012 Verify acceptance criteria are covered with concrete documentation evidence.
+- [x] T013 Update process memory with final decisions, dead ends, known issues, and verification evidence.
+
+## Process Memory
+
+### Dead Ends
+
+- None.
+
+### Decisions
+
+- Treat this as a process documentation feature, not an executable workflow-enforcement feature.
+- Apply "every request" to repository-changing requests, including process-rule and documentation changes.
+- Keep implementation out of product code and workflow scripts.
+- Use `AGENTS.md` as the durable role-boundary source for this change because the targeted search found the stale Orchestrator ownership language there.
+- Leave unrelated untracked build artifact directories untouched: `dist/`, `node_modules/`, `public/`, and `test-results/`.
+- Rebase onto `origin/main` before final PR handoff and resolve the single `AGENTS.md` conflict by preserving both the repository-changing scope and the no-direct-push-to-main rule.
+
+### Known Issues
+
+- Executable enforcement of this boundary is not part of this feature.
+- `specs/002-orchestrator-role-boundary/` remains untracked in this worktree, so `git diff --name-only` shows only tracked-file changes; `git status --short` is needed to see this feature-memory update.
+
+### Verification Evidence
+
+- Branch/worktree: `git switch -c codex/002-orchestrator-role-boundary` succeeded before file edits.
+- Old Orchestrator ownership search: `rg -n "Creates or updates feature memory|Creates or updates feature-memory|Orchestrator.*Creates|Orchestrator.*updates feature memory|Orchestrator.*create.*feature memory|Orchestrator.*update.*feature memory" AGENTS.md docs_project .specify/memory/constitution.md` returned no matches.
+- Release old-language search: `rg -n "Creates or updates feature memory before product-code changes|Creates or updates feature memory before|Orchestrator.*Creates or updates feature memory|Orchestrator.*feature memory before product-code" AGENTS.md docs_project .specify/memory/constitution.md` returned no matches.
+- New role-boundary search: `rg -n "### Architect|repository-changing user request|Must not directly edit|must not directly edit|Starts from assigned feature memory|complete feature memory|role boundaries|Coordinates assigned agents" AGENTS.md` found the Architect role, repository-changing request rule, Orchestrator no-direct-edit rule, Implementation Agent handoff rule, and Review Agent compliance rule.
+- Scope check: `git diff --name-only` returned only `AGENTS.md` among tracked files.
+- Worktree check: `git status --short` showed `M AGENTS.md`, untracked `specs/002-orchestrator-role-boundary/`, and unrelated untracked artifact directories `dist/`, `node_modules/`, `public/`, and `test-results/`.
+- Whitespace check: `git diff --check` passed.
+- Feature-memory check: `node scripts/check-feature-memory.mjs --worktree` passed with `No configured product paths changed; feature-memory gate passes.`
+- Local preflight: `pnpm run preflight` passed, including `check:feature-memory` and `check:repo`.
+- Documentation evidence: `AGENTS.md` lines 34-40 define Architect ownership of `spec.md`, `plan.md`, and `tasks.md`; lines 42-50 define Orchestrator coordination/enforcement and no direct repository edits; lines 54-57 define Implementation Agent handoff and task upkeep; lines 62-65 define Review Agent compliance checks; lines 73-74 require one feature folder and complete feature memory for repository-changing requests.
+- Rebase evidence: `git rebase origin/main` found one `AGENTS.md` conflict in Delivery Workflow, resolved as `Repository-changing work lands through pull requests; do not push directly to main`.