Add role-based agent templates

README.md

@@ -63,11 +63,11 @@ agentrail server start
 In another terminal, verify setup:
 
 ```bash
-agentrail doctor
+agentrail doctor --agent-id agt_example
 ```
 
 `doctor` is the success gate. It checks the local API, agent credentials,
-profile/routing state, and whether the current agent can see assigned work.
+profile/routing state, and whether the selected agent can see assigned work.
 
 ## Telemetry
 
@@ -132,6 +132,34 @@ agentrail agent create
 agentrail agent update --agent-id agt_example
 ```
 
+Use a built-in role template, or install your own YAML-backed role template:
+
+```bash
+agentrail agent create --role-template frontend-ui
+agentrail agent create --role-template-file ./agent-roles/payments-backend.yaml
+```
+
+Custom templates are validated and copied into
+`~/.agentrail/agent-role-templates/`, so later agents can reuse them with
+`--role-template <id>`.
+
+During `agentrail init` and `agentrail repo add`, AgentRail also creates an
+editable repo map under `~/.agentrail/repo-maps/<repo>.yaml`. Role templates use
+repo-agnostic areas such as `frontend_source`, `tests`, and `ci_configuration`;
+the repo map translates those areas to the actual folders in your project.
+The starter map is generated deterministically. During interactive setup you can
+also let a local Codex, Claude Code, or Cursor runner propose a richer map;
+AgentRail validates the proposal, shows you the summary and warnings, and falls
+back to the starter map if the local runner is unavailable or uncertain.
+
+When a managed agent starts work, AgentRail combines the selected role template
+with the repo map for that repository and passes a compact role brief to the
+runner. The brief points the agent at relevant repo areas and validation
+expectations, while AgentRail still owns lifecycle actions such as PR creation,
+CI watching, review handling, and shipping. If a repo map is missing or
+incomplete, AgentRail still runs the agent and includes a warning in the run
+context. Run `agentrail doctor` to check repo-map coverage.
+
 Inspect local config and connected repos:
 
 ```bash

defaults/agent-roles/README.md

@@ -21,3 +21,38 @@ The templates are also deliberately repo-neutral. Workspace entries use abstract
 areas such as `backend_source`, `api_contracts`, `tests`, or `ci_configuration`
 instead of concrete path globs. A project-level repo profile should map those
 areas to actual paths during `agentrail init` or a later template-tailoring step.
+
+`agentrail init` and `agentrail repo add` create editable repo maps under
+`~/.agentrail/repo-maps/<repo>.yaml`. Keep concrete paths there, not in role
+templates. The starter map is deterministic by default, and interactive setup
+can optionally ask a local Codex, Claude Code, or Cursor runner to propose a
+richer map. AgentRail validates the proposal before saving it and keeps the
+starter map when the local runner is unavailable or uncertain.
+
+When a managed agent starts work, AgentRail combines the selected role template
+with the repo map for that repository and passes a compact role brief to the
+runner. The brief points the agent at relevant repo areas and validation
+expectations, while AgentRail still owns lifecycle actions such as PR creation,
+CI watching, review handling, and shipping.
+
+If a repo map is missing or incomplete, AgentRail still runs the agent and
+includes a warning in the run context. Run `agentrail doctor` to check repo-map
+coverage.
+
+## Custom Templates
+
+Install a custom role template from a local YAML file when creating or updating
+an agent:
+
+```bash
+agentrail agent create --role-template-file ./agent-roles/payments-backend.yaml
+agentrail agent update --agent-id agt_payments --role-template-file ./agent-roles/payments-backend.yaml
+```
+
+AgentRail validates the YAML, rejects IDs that collide with built-in templates,
+and stores the installed copy under `~/.agentrail/agent-role-templates/<id>.yaml`.
+After that, reuse it by ID:
+
+```bash
+agentrail agent create --role-template payments-backend
+```

defaults/agent-roles/backend-api.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: backend-api
 name: Backend/API
+role: coding_agent
 description: Handles server code, APIs, provider adapters, lifecycle behavior, data contracts, and backend tests.
 
 routing:

defaults/agent-roles/ci-release.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: ci-release
 name: CI/Release
+role: release_agent
 description: Handles CI failures, workflow configuration, package publishing, deployment readiness, and release automation.
 
 routing:

defaults/agent-roles/code-review.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: code-review
 name: Code Review
+role: review_agent
 description: Reviews code changes for correctness, regressions, security risks, maintainability, and missing tests.
 
 routing:

defaults/agent-roles/debugger.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: debugger
 name: Debugger
+role: coding_agent
 description: Investigates failures, reproduces bugs, identifies root causes, and applies narrow fixes when requested.
 
 routing:

defaults/agent-roles/docs.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: docs
 name: Docs
+role: docs_agent
 description: Handles documentation, guides, README updates, SDK examples, changelogs, and release notes.
 
 routing:

defaults/agent-roles/frontend-ui.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: frontend-ui
 name: Frontend/UI
+role: coding_agent
 description: Handles frontend application code, visual polish, responsive layout, accessibility, and browser-facing interactions.
 
 routing:

defaults/agent-roles/security.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: security
 name: Security
+role: review_agent
 description: Reviews and fixes security-sensitive code, auth boundaries, secret handling, webhooks, sandboxing, and permission policies.
 
 routing:

defaults/agent-roles/test-automation.yaml

@@ -1,6 +1,7 @@
 schemaVersion: agentrail.agent-role/v1
 id: test-automation
 name: Test Automation
+role: coding_agent
 description: Adds, repairs, and strengthens automated tests, fixtures, smoke tests, and validation scripts.
 
 routing:

docs/api/intake-routing-admin.openapi.yaml

@@ -96,6 +96,7 @@ paths:
                         assignmentSource: deterministic_rule
                         routingDecisionId: rdec_01JZROUTE0000000000000001
                         assignedAt: '2026-05-05T12:01:03Z'
+                        roleTemplate: null
                       confidence: 0.99
                       routingReason:
                         summary: Repo agentrail plus labels architecture/api matched CTO ownership rule.
@@ -303,6 +304,7 @@ paths:
                       agentId: agt_cto
                       displayName: CTO
                       role: cto
+                      roleTemplateId: backend-api
                       status: active
                       capabilityTags: [api-design, architecture, security-review]
                       ownershipTags: [control-plane, docs]
@@ -344,6 +346,7 @@ paths:
                 value:
                   displayName: CTO
                   role: cto
+                  roleTemplateId: backend-api
                   status: active
                   capabilityTags: [api-design, architecture, security-review]
                   ownershipTags: [control-plane, docs]
@@ -365,6 +368,7 @@ paths:
                       agentId: agt_cto
                       displayName: CTO
                       role: cto
+                      roleTemplateId: backend-api
                       status: active
                       capabilityTags: [api-design, architecture, security-review]
                       ownershipTags: [control-plane, docs]
@@ -394,7 +398,7 @@ paths:
       description: |
         Creates one deterministic setup smoke task per selected `agentId`.
         The task is assigned directly to that agent and stays in
-        `in_progress` so the setup runner can prove `GET /tasks/mine` works.
+        `in_progress` so the managed runner can prove its run-scoped context works.
         The CLI pairs this endpoint with `agentrail doctor`; setup is not
         complete until the generated agent key can read the task from
         `GET /tasks/mine?status=in_progress&limit=1`.
@@ -509,6 +513,7 @@ paths:
                         assignmentSource: manual_triage
                         routingDecisionId: rdec_01JZROUTE0000000000000200
                         assignedAt: null
+                        roleTemplate: null
                       confidence: 0
                       routingReason:
                         summary: No deterministic route matched; AI routing could not find a suitable agent, so the task is waiting for a suitable agent.
@@ -560,6 +565,7 @@ paths:
                           assignmentSource: deterministic_rule
                           routingDecisionId: rdec_01JZROUTE0000000000000001
                           assignedAt: '2026-05-05T12:01:03Z'
+                          roleTemplate: null
                         confidence: 0.99
                         routingReason:
                           summary: Repo agentrail plus labels architecture/api matched CTO ownership rule.
@@ -701,6 +707,8 @@ components:
       properties:
         requestId:
           type: string
+        routingRetry:
+          $ref: '#/components/schemas/RoutingRetryResult'
     ErrorResponse:
       type: object
       additionalProperties: false
@@ -813,6 +821,10 @@ components:
           type: string
         role:
           type: string
+        roleTemplateId:
+          type: [string, 'null']
+          description: Optional built-in or custom role template id used to create this agent profile.
+          pattern: '^[a-z][a-z0-9-]*$'
         status:
           type: string
           enum: [active, paused, disabled]
@@ -865,6 +877,10 @@ components:
           type: string
         role:
           type: string
+        roleTemplateId:
+          type: [string, 'null']
+          description: Optional built-in or custom role template id used to create this agent profile.
+          pattern: '^[a-z][a-z0-9-]*$'
         status:
           type: string
           enum: [active, paused, disabled]
@@ -1191,20 +1207,56 @@ components:
     TaskAssignment:
       type: object
       additionalProperties: false
-      required: [assigneeAgentId, triageQueueId, assignmentSource, routingDecisionId, assignedAt]
+      required: [assigneeAgentId, triageQueueId, assignmentSource, routingDecisionId, assignedAt, roleTemplate]
       properties:
         assigneeAgentId:
           type: [string, 'null']
         triageQueueId:
           type: [string, 'null']
         assignmentSource:
           type: string
-          enum: [deterministic_rule, classifier, classifier_best_effort, manual_triage]
+          enum: [deterministic_rule, classifier, classifier_best_effort, single_agent_fallback, manual_triage]
         routingDecisionId:
           type: string
         assignedAt:
           type: [string, 'null']
           format: date-time
+        roleTemplate:
+          anyOf:
+            - type: 'null'
+            - $ref: '#/components/schemas/RoutingAssignmentRoleTemplate'
+    RoutingAssignmentRoleTemplate:
+      type: object
+      additionalProperties: false
+      required: [id, name, sourceKind]
+      properties:
+        id:
+          type: string
+          pattern: '^[a-z][a-z0-9-]*$'
+        name:
+          type: string
+        sourceKind:
+          type: string
+          enum: [built_in, custom, unknown]
+    RoutingRetryResult:
+      type: object
+      additionalProperties: false
+      required: [scanned, assigned, unchanged, skipped]
+      properties:
+        scanned:
+          type: integer
+          minimum: 0
+        assigned:
+          type: integer
+          minimum: 0
+        unchanged:
+          type: integer
+          minimum: 0
+        skipped:
+          type: integer
+          minimum: 0
+        error:
+          type: string
     RoutingReason:
       type: object
       additionalProperties: false

docs/architecture/local-self-hosted-setup-cli-contract.md

@@ -130,8 +130,8 @@ Review setup plan:
 - After server start, create AgentIdentity agt_codex_local
 - Create AgentProfile for oxnw/agentrail
 - Create starter routing and setup verification task
-- Write .agentrail/agent.env with mode 0600
-- Run agentrail doctor and require /tasks/mine to return assigned work
+- Write .agentrail/agents/agt_codex_local.env with mode 0600
+- Run agentrail doctor --agent-id agt_codex_local and require /tasks/mine to return assigned work
 
 ? Continue
   Yes
@@ -314,8 +314,8 @@ The local/self-hosted data model should stay cloud-shaped:
   store. The important boundary is that the store is queryable, versioned, and
   compatible with API semantics; ad hoc Markdown parsing is not acceptable.
 - `.agentrail/config.json` stores non-secret configuration only.
-- `.agentrail/agent.env` stores generated local agent secrets and must be
-  created with mode `0600`.
+- `.agentrail/agents/<agentId>.env` stores generated local agent secrets and
+  must be created with mode `0600`.
 - Optional Markdown export writes snapshots such as
   `.agentrail/notes/tasks/<task-id>.md`,
   `.agentrail/notes/routing/<decision-id>.md`, and
@@ -412,7 +412,7 @@ Expected response fields used by the CLI:
 }
 ```
 
-The CLI stores only `data.apiKey` in `.agentrail/agent.env`, never in
+The CLI stores only `data.apiKey` in `.agentrail/agents/<agentId>.env`, never in
 `.agentrail/config.json`. The key ID is not sufficient for authentication and
 must not be printed as if it were a secret.
 
@@ -457,13 +457,14 @@ create or ingest one setup verification task through the normal assignment path.
 Real provider mode may use a selected provider issue instead, but it must still
 end with an assigned AgentRail task visible to the new agent.
 
-The CLI must run `agentrail doctor` after registration. Success means the
-generated key can call `/tasks/mine` against the configured base URL.
+The CLI must run `agentrail doctor --agent-id <agentId>` after registration.
+Success means the generated key can call `/tasks/mine` against the configured
+base URL.
 
 ## Smoke Tests And Success Gate
 
-`agentrail doctor` is part of setup, not an optional diagnostic. Setup reports
-success only after these checks pass:
+`agentrail doctor --agent-id <agentId>` is part of setup, not an optional
+diagnostic. Setup reports success only after these checks pass:
 
 1. `GET /health` returns `status: "ok"` from the configured base URL.
 2. In auth-enabled mode, the generated `AGENTRAIL_API_KEY` authenticates as the
@@ -500,7 +501,8 @@ command instead of telling the user to start the LLM agent.
 
 ## Agent Env Output
 
-`agentrail agent create` writes `.agentrail/agent.env` with mode `0600`:
+`agentrail agent create` writes `.agentrail/agents/agt_codex_local.env` with
+mode `0600`:
 
 ```bash
 AGENTRAIL_BASE_URL=http://127.0.0.1:3000
@@ -516,19 +518,19 @@ It also prints the next command for the selected runner.
 Codex:
 
 ```bash
-source .agentrail/agent.env && cd /path/to/target-repo && codex
+agentrail agent run --agent-id agt_codex_local --once
 ```
 
 Claude Code:
 
 ```bash
-source .agentrail/agent.env && cd /path/to/target-repo && claude --append-system-prompt-file "$AGENTRAIL_AGENT_RECIPE_PATH"
+source .agentrail/agents/agt_claude_local.env && cd /path/to/target-repo && claude --append-system-prompt-file "$AGENTRAIL_AGENT_RECIPE_PATH"
 ```
 
 Cursor:
 
 ```bash
-source .agentrail/agent.env && cursor /path/to/target-repo
+source .agentrail/agents/agt_cursor_local.env && cursor /path/to/target-repo
 ```
 
 For Cursor, the CLI should also write or update a project rule that contains
@@ -582,11 +584,11 @@ surface before the underlying auth and routing contracts are stable.
   equivalent command.
 - All server mutations use deterministic payload-derived idempotency keys so
   exact replays are safe and later edits do not collide with earlier requests.
-- `agentrail agent create --rotate-key` rotates the API key and rewrites
-  `.agentrail/agent.env`.
+- `agentrail agent update --agent-id <agentId>` rotates the API key and rewrites
+  `.agentrail/agents/<agentId>.env`.
 - Real provider mode fails closed when required provider token env vars are
   missing.
-- The CLI never commits `.agentrail/agent.env`, provider tokens, or generated
+- The CLI never commits `.agentrail/agents/*.env`, provider tokens, or generated
   AgentRail API keys.
 - The first auth-enabled local setup run may create an admin key through the
   documented auth creation path. Later setup calls require the admin key or a