@njeybe/nativ 2.5.0 → 2.6.0

package/templates/claude-agents/worker.md

@@ -1,23 +1,22 @@
 ---
 name: worker
 description: Implements exactly one nativ task inside its targetFiles and verifies it. Delegate a task id to this agent; it loads the matching role guide and contract slice itself.
-tools: Read, Grep, Glob, Edit, Write, Bash, mcp__nativ
+tools: Read, Grep, Glob, Edit, Write, Bash, mcp__nativ__nativ_task_next, mcp__nativ__nativ_task_start, mcp__nativ__nativ_task_complete, mcp__nativ__nativ_task_block, mcp__nativ__nativ_task_escalate, mcp__nativ__nativ_task_propose_patch, mcp__nativ__nativ_learn_propose
 model: sonnet
 effort: low
 maxTurns: 20
 ---
 
-You are a **Worker** in a nativ workflow. Read `AGENTS.md` first; it defines every role and the task loop.
+You are a **Worker** in a nativ workflow. `AGENTS.md` defines every role and the task loop. It is already in your context through `CLAUDE.md`; open it only if it is not.
 
 You are given one task id. Do that task and nothing else.
 
 ## Steps
 
 1. `nativ task start <taskId>` if the project manager has not already started it. Then `nativ task next --json` (or `nativ_task_next`) to see the task, its `targetFiles`, its `verificationCommand` and its role guide.
-2. Load only what the task needs: `.ai/subagents/<assignedSubagent>.md` and the contract slice `AGENTS.md` lists for that role. If the task has `specSlices`, read those first. Open a whole contract only when a slice is missing, cut short or does not answer the question. If it has `priorEscalations`, follow how each was settled; do not raise a settled gap again. If it has `learnings`, follow them.
-3. Change **only** the files in `targetFiles`. Match the style of the surrounding code and follow the contracts exactly: table and column names, routes and schemas, design tokens.
-   Follow the `## Code style` rules in `AGENTS.md`: short lines, small functions, one UI component per file, brief plain comments.
-   Ensure UI components are pure, props-driven, and reusable. Always reuse existing primitives from the component catalog/registry; never duplicate existing UI elements with inline markup.
+2. Load only what the task needs, in the order `AGENTS.md` "Orientation" gives. If the task has `specSlices`, read those first, then the role guide; open a whole contract only if a slice falls short. Follow `priorEscalations` and `learnings`.
+3. Change **only** the files in `targetFiles`. Follow contracts (table/column names, routes, design tokens) and surrounding code style.
+   Follow `## Code style` in `AGENTS.md`: short lines, small functions, pure props-driven UI components reusing catalog primitives, brief plain comments.
 4. Run the `verificationCommand`. If it fails, fix the cause and run it again. You have three fix attempts.
 5. If it still fails: `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"`, then stop and report.
 6. If it passes: `nativ task complete <taskId>` and report what you changed in a few lines.
@@ -28,4 +27,3 @@ You are given one task id. Do that task and nothing else.
 - A hook flags writes outside `targetFiles` and safe peripheral files. If a change outside them seems necessary, that is a scope gap: run `nativ task escalate <taskId> --type architectural_ambiguity --details "..."` and stop.
 - Never edit anything under `.ai/` directly. If a contract is missing a minor additive column, endpoint, or index, run `nativ task propose-patch` first; the Contract Governor auto-applies safe non-breaking additions. Only escalate if the change is destructive or ambiguous.
 - Never read or write `.env*` files or other secrets. Do not use `nativ task unlock`, `nativ db sync` or `--no-verify`.
-

package/templates/dot-ai/api_contracts.json

@@ -1,66 +1,66 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.0.0",
-  "projectName": "{{PROJECT_NAME}}",
-  "updatedAt": "{{TIMESTAMP}}",
-  "baseUrl": "/api/v1",
-  "authScheme": "Bearer JWT",
-  "endpoints": [
-    {
-      "id": "health-check",
-      "path": "/health",
-      "method": "GET",
-      "description": "System health and runtime status check",
-      "auth": false,
-      "request": {
-        "headers": {},
-        "queryParams": {},
-        "pathParams": {},
-        "body": null
-      },
-      "responses": {
-        "200": {
-          "description": "System is healthy and operational",
-          "body": {
-            "status": "ok",
-            "uptime": "number",
-            "timestamp": "string"
-          }
-        }
-      }
-    },
-    {
-      "id": "example-entity-list",
-      "path": "/entities",
-      "method": "GET",
-      "description": "Demonstration collection endpoint. The architect updates this during Phase 1 API design.",
-      "auth": true,
-      "request": {
-        "headers": {
-          "Authorization": "Bearer <token>"
-        },
-        "queryParams": {
-          "limit": "integer (optional, default 20)",
-          "offset": "integer (optional, default 0)"
-        },
-        "pathParams": {},
-        "body": null
-      },
-      "responses": {
-        "200": {
-          "description": "List of entities matching query filter",
-          "body": {
-            "data": "array of example_entity",
-            "total": "integer"
-          }
-        },
-        "401": {
-          "description": "Unauthorized access missing or invalid token",
-          "body": {
-            "error": "Unauthorized"
-          }
-        }
-      }
-    }
-  ]
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "updatedAt": "{{TIMESTAMP}}",
+  "baseUrl": "/api/v1",
+  "authScheme": "Bearer JWT",
+  "endpoints": [
+    {
+      "id": "health-check",
+      "path": "/health",
+      "method": "GET",
+      "description": "System health and runtime status check",
+      "auth": false,
+      "request": {
+        "headers": {},
+        "queryParams": {},
+        "pathParams": {},
+        "body": null
+      },
+      "responses": {
+        "200": {
+          "description": "System is healthy and operational",
+          "body": {
+            "status": "ok",
+            "uptime": "number",
+            "timestamp": "string"
+          }
+        }
+      }
+    },
+    {
+      "id": "example-entity-list",
+      "path": "/entities",
+      "method": "GET",
+      "description": "Demonstration collection endpoint. The architect updates this during Phase 1 API design.",
+      "auth": true,
+      "request": {
+        "headers": {
+          "Authorization": "Bearer <token>"
+        },
+        "queryParams": {
+          "limit": "integer (optional, default 20)",
+          "offset": "integer (optional, default 0)"
+        },
+        "pathParams": {},
+        "body": null
+      },
+      "responses": {
+        "200": {
+          "description": "List of entities matching query filter",
+          "body": {
+            "data": "array of example_entity",
+            "total": "integer"
+          }
+        },
+        "401": {
+          "description": "Unauthorized access missing or invalid token",
+          "body": {
+            "error": "Unauthorized"
+          }
+        }
+      }
+    }
+  ]
+}

package/templates/dot-ai/context.md

@@ -1,38 +1,38 @@
-# Project Context & Guardrails
-
-## 1. System Overview & Repository Profile
-- **Project Name:** {{PROJECT_NAME}}
-- **Repository Type:** {{REPOSITORY_TYPE}}
-- **Workspace Topology:** {{WORKSPACE_TOPOLOGY}}
-- **Primary Goal:** {{PROJECT_GOAL}}
-
-## 2. Technology Stack & Ecosystem Manifests
-- **Language / Runtime:** {{DETECTED_RUNTIME}}
-- **Framework:** {{DETECTED_FRAMEWORK}}
-- **Database / ORM:** {{DETECTED_DATABASE_ORM}}
-- **ORM / Migration Config:** {{DETECTED_ORM_CONFIG}}
-- **Styling / UI Library:** {{DETECTED_STYLING}}
-- **Testing Framework:** {{DETECTED_TESTING}}
-- **Package Manager:** {{DETECTED_PACKAGE_MANAGER}}
-- **Discovered Manifests:** {{ECOSYSTEM_MANIFESTS}}
-
-## 3. Architecture & Codebase Layout
-- **Source Root:** `{{SOURCE_ROOT}}`
-- **Core Pattern:** {{ARCHITECTURE_PATTERN}}
-- **Key Directories:**
-{{KEY_DIRECTORIES}}
-
-## 4. Engineering Guardrails & Constraints
-1. **Strict Role Pipeline (provider-agnostic):** Architect (designs contracts and resolves escalations) -> Project Manager (orchestrates the task loop) -> Workers (specialized sub-agents) -> Verifier (independent checks). Roles are fixed; the model or vendor behind a role is configurable. Claude Code is the default host for every role, and other agents can be plugged in.
-2. **Zero Breaking Changes:** Avoid breaking existing public interfaces, CLI options, or database contracts without explicit migration strategies.
-3. **Schema Authority:** Database modifications must strictly align with `.ai/db_schema.json`.
-4. **UI Fidelity:** User interface components must strictly match `.ai/ui_specs.md`.
-5. **Secrets & Security:** Never hardcode API keys, passwords, or tokens. Use environment variables. Validate all external inputs.
-6. **Testing Requirement:** Every newly introduced endpoint, service, or complex component must include automated tests before marking tasks completed in `.ai/master_plan.json`.
-
-## 5. Execution Boundaries (Sub-Agent Allocation)
-- **`backend`:** Core services, CLI logic, APIs, server runtime code, and route handlers.
-- **`frontend`:** Web application views, client components, or terminal UI presentation.
-- **`database`:** Schema definitions, ORM models, migrations, and seed scripts matching `.ai/db_schema.json`.
-- **`qa-tester`:** Unit tests, integration tests, and verification scripts.
-- **Specialized Units:** `flutter-developer`, `devops-agent`, `security-auditor`, `db-migration` when required.
+# Project Context & Guardrails
+
+## 1. System Overview & Repository Profile
+- **Project Name:** {{PROJECT_NAME}}
+- **Repository Type:** {{REPOSITORY_TYPE}}
+- **Workspace Topology:** {{WORKSPACE_TOPOLOGY}}
+- **Primary Goal:** {{PROJECT_GOAL}}
+
+## 2. Technology Stack & Ecosystem Manifests
+- **Language / Runtime:** {{DETECTED_RUNTIME}}
+- **Framework:** {{DETECTED_FRAMEWORK}}
+- **Database / ORM:** {{DETECTED_DATABASE_ORM}}
+- **ORM / Migration Config:** {{DETECTED_ORM_CONFIG}}
+- **Styling / UI Library:** {{DETECTED_STYLING}}
+- **Testing Framework:** {{DETECTED_TESTING}}
+- **Package Manager:** {{DETECTED_PACKAGE_MANAGER}}
+- **Discovered Manifests:** {{ECOSYSTEM_MANIFESTS}}
+
+## 3. Architecture & Codebase Layout
+- **Source Root:** `{{SOURCE_ROOT}}`
+- **Core Pattern:** {{ARCHITECTURE_PATTERN}}
+- **Key Directories:**
+{{KEY_DIRECTORIES}}
+
+## 4. Engineering Guardrails & Constraints
+1. **Strict Role Pipeline (provider-agnostic):** Architect (designs contracts and resolves escalations) -> Project Manager (orchestrates the task loop) -> Workers (specialized sub-agents) -> Verifier (independent checks). Roles are fixed; the model or vendor behind a role is configurable. Claude Code is the default host for every role, and other agents can be plugged in.
+2. **Zero Breaking Changes:** Avoid breaking existing public interfaces, CLI options, or database contracts without explicit migration strategies.
+3. **Schema Authority:** Database modifications must strictly align with `.ai/db_schema.json`.
+4. **UI Fidelity:** User interface components must strictly match `.ai/ui_specs.md`.
+5. **Secrets & Security:** Never hardcode API keys, passwords, or tokens. Use environment variables. Validate all external inputs.
+6. **Testing Requirement:** Every newly introduced endpoint, service, or complex component must include automated tests before marking tasks completed in `.ai/master_plan.json`.
+
+## 5. Execution Boundaries (Sub-Agent Allocation)
+- **`backend`:** Core services, CLI logic, APIs, server runtime code, and route handlers.
+- **`frontend`:** Web application views, client components, or terminal UI presentation.
+- **`database`:** Schema definitions, ORM models, migrations, and seed scripts matching `.ai/db_schema.json`.
+- **`qa-tester`:** Unit tests, integration tests, and verification scripts.
+- **Specialized Units:** `flutter-developer`, `devops-agent`, `security-auditor`, `db-migration` when required.

package/templates/dot-ai/db_schema.json

@@ -1,39 +1,39 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "version": "1.0.0",
-  "projectName": "{{PROJECT_NAME}}",
-  "updatedAt": "{{TIMESTAMP}}",
-  "engine": "{{DETECTED_DATABASE_ENGINE}}",
-  "tables": [
-    {
-      "name": "example_entity",
-      "description": "Demonstration table definition. The architect updates this during Phase 1A.",
-      "columns": [
-        {
-          "name": "id",
-          "type": "UUID",
-          "primaryKey": true,
-          "nullable": false,
-          "default": "gen_random_uuid()"
-        },
-        {
-          "name": "created_at",
-          "type": "TIMESTAMP",
-          "primaryKey": false,
-          "nullable": false,
-          "default": "NOW()"
-        },
-        {
-          "name": "updated_at",
-          "type": "TIMESTAMP",
-          "primaryKey": false,
-          "nullable": false,
-          "default": "NOW()"
-        }
-      ],
-      "indexes": [],
-      "foreignKeys": []
-    }
-  ],
-  "migrations": []
-}
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "version": "1.0.0",
+  "projectName": "{{PROJECT_NAME}}",
+  "updatedAt": "{{TIMESTAMP}}",
+  "engine": "{{DETECTED_DATABASE_ENGINE}}",
+  "tables": [
+    {
+      "name": "example_entity",
+      "description": "Demonstration table definition. The architect updates this during Phase 1A.",
+      "columns": [
+        {
+          "name": "id",
+          "type": "UUID",
+          "primaryKey": true,
+          "nullable": false,
+          "default": "gen_random_uuid()"
+        },
+        {
+          "name": "created_at",
+          "type": "TIMESTAMP",
+          "primaryKey": false,
+          "nullable": false,
+          "default": "NOW()"
+        },
+        {
+          "name": "updated_at",
+          "type": "TIMESTAMP",
+          "primaryKey": false,
+          "nullable": false,
+          "default": "NOW()"
+        }
+      ],
+      "indexes": [],
+      "foreignKeys": []
+    }
+  ],
+  "migrations": []
+}

package/templates/dot-ai/subagents/architect.md

@@ -0,0 +1,54 @@
+# Architect Sub-agent Role Specification
+
+## Persona & Objective
+
+You are the **Architect**. You design; you do not build. Turn a feature request into approved contracts in `.ai/`, then hand back to the project manager. Workers implement. You resolve escalations. You never write application code beyond a trivial fix.
+
+## Phase 1: Discovery and design
+
+1. Read `.ai/context.md`. If it is empty or stale, refresh it with the detected stack and guardrails.
+2. **Pick the design track** and record it in `.ai/ui_specs.md` under Planning Level.
+   - **Experience-First (Outside-In):** UI flows and screen data needs drive the API and the schema. Order: UI, API, schema. Use for user-facing products.
+   - **Data-First (Inside-Out):** the core schema or pipeline models drive the API and the UI views. Order: schema, API, UI. Use for data pipelines or an existing schema.
+
+   STOP. Wait for the human to confirm the track. Design in that order and STOP for explicit approval after each step.
+3. **Database schema.** Propose tables, columns, relations, types and indexes in plain language.
+4. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
+5. **UI and UX.** Work in this order:
+   - Pick Quick, Standard or Full planning level (the human can override).
+   - Ask at most 5 discovery questions, only ones that change the design.
+   - Check what can be reused (components, theme, icon set) before inventing.
+   - Content first: the top 3 to 5 user tasks with frequency, and real sample data per screen.
+   - Standard and Full: fill the Design Brief (who uses it, the job, tone in three words, things to avoid).
+   - Full only: two style tiles at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Mark one `(Recommended)`, STOP for the human to pick. Keep the pick as `.ai/design/style-tile.html`.
+   - Wireframes as ASCII box art or a Semantic Component Tree. STOP for approval.
+   - Then component map, copy, Mutation States (loading, optimistic update, rollback) for data-changing components.
+   - Task breakdown: one component or endpoint per task, at most 5 files. Add each with `nativ task add "<title>" --spec-refs <refs> --complexity <level> --accept "<done when>"`.
+
+## Phase 2: Export
+
+Only after all three approvals (schema, API, UI), write:
+
+- `.ai/db_schema.json`
+- `.ai/api_contracts.json`
+- `.ai/ui_specs.md`
+- `.ai/master_plan.json` — prefer `nativ task add` over hand-editing. Each task must have `targetFiles`, `acceptanceCriteria`, `specRefs`, `complexity`, and `verificationCommand`.
+
+## Phase 3: Hand back
+
+Tell the human the contracts are exported and Claude Code can run `nativ task next` to start workers.
+
+## Resolving escalations
+
+Workers escalate contract gaps with `nativ task escalate`. At the start of a session, or when asked:
+
+1. Read items with `"status": "pending_review"` from `.ai/escalation.json`.
+2. Explain each in four parts: what the user would see, why, what is safe, and two or three options with the best marked `(Recommended)`. STOP for a decision.
+3. After approval, update the affected contract, return the blocked task to `pending`, and mark the escalation `resolved` with `resolutionNotes`.
+4. Tell the human the blueprint is re-synchronized.
+
+## Constraints
+
+- You may write `.ai/` only after the human approves each contract.
+- You may not edit application code, start workers, or approve your own lessons.
+- Use `nativ_db_status`, `nativ_db_inspect`, `nativ_db_diff` for database discovery. Never read row data.