@njeybe/nativ 2.0.2 → 2.2.0

package/dist/core/verifier.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { exec } from 'node:child_process';
+import { checkCodeShape, formatCodeShapeReport } from './code-shape.js';
 export function loadMasterPlan(targetDir) {
     const planPath = path.join(targetDir, '.ai', 'master_plan.json');
     if (!fs.existsSync(planPath)) {
@@ -76,6 +77,27 @@ export async function executeVerification(command, cwd, timeoutMs = 120_000) {
         });
     });
 }
+/**
+ * Run the code-shape check on a task's target files and print a short summary to stderr.
+ * In 'warn' mode (default) the result is untouched; in 'block' mode issues fail it with a reason.
+ */
+export function applyCodeShape(result, targetDir, task) {
+    if (result.skipped || !result.success)
+        return result;
+    const report = checkCodeShape(targetDir, task.targetFiles || []);
+    if (report.mode === 'off')
+        return result;
+    result.codeShape = report;
+    const summary = formatCodeShapeReport(report);
+    if (summary)
+        console.error(summary);
+    if (report.mode === 'block' && report.issues.length > 0) {
+        result.success = false;
+        result.exitCode = 1;
+        result.error = `Code shape check failed: ${report.issues.length} issue(s) (codeStyle.mode is "block")`;
+    }
+    return result;
+}
 /**
  * Run verification for a single specific task in the plan.
  */
@@ -128,7 +150,8 @@ export async function verifyTask(taskId, targetDirArg, options = {}) {
             },
         };
     }
-    const result = await executeVerification(foundTask.verificationCommand, targetDir, options.timeout);
+    const raw = await executeVerification(foundTask.verificationCommand, targetDir, options.timeout);
+    const result = applyCodeShape(raw, targetDir, foundTask);
     return {
         taskId: foundTask.id,
         title: foundTask.title,
@@ -217,7 +240,8 @@ export async function verifyBatch(targetDirArg, options = {}) {
     let skipped = 0;
     let totalDuration = 0;
     for (const { task, milestone } of candidates) {
-        const vResult = await executeVerification(task.verificationCommand, targetDir, options.timeout);
+        const raw = await executeVerification(task.verificationCommand, targetDir, options.timeout);
+        const vResult = applyCodeShape(raw, targetDir, task);
         totalDuration += vResult.durationMs;
         if (vResult.skipped) {
             skipped++;

package/dist/index.js

@@ -126,6 +126,9 @@ export function createProgram() {
         .option('-d, --description <text>', 'Task description')
         .option('--fast-path', 'Route to the fast-path milestone (created on first use) and flag the task as fast path')
         .option('--deps <ids>', 'Comma-separated dependency task IDs')
+        .option('--spec-refs <refs>', 'Comma-separated spec anchors, e.g. ui_specs.md#appointment-list')
+        .option('--complexity <level>', 'Task complexity: simple, standard or complex')
+        .option('--accept <text>', 'Acceptance ("done when") line; repeatable or "|"-separated', (value, prev = []) => [...prev, value])
         .option('--json', 'Output the created task as JSON')
         .action(async (title, targetDir, options) => {
         await runTaskAdd(title, targetDir, options);

package/dist/mcp/server.js

@@ -103,8 +103,11 @@ export function createMcpServer(targetDirArg) {
             targetFiles: z.array(z.string()).optional().describe('Files the task may modify'),
             dependencies: z.array(z.string()).optional().describe('Task IDs that must be completed first'),
             fastPath: z.boolean().optional().describe('Route to the fast-path track'),
+            specRefs: z.array(z.string()).optional().describe('Spec anchors, e.g. ui_specs.md#appointment-list'),
+            complexity: z.string().optional().describe('simple, standard or complex'),
+            acceptanceCriteria: z.array(z.string()).optional().describe('Plain-language "done when" lines'),
         },
-    }, ({ title, description, assignedSubagent, milestone, verificationCommand, targetFiles, dependencies, fastPath }) => captureOutput(() => runTaskAdd(title, targetDir, {
+    }, ({ title, description, assignedSubagent, milestone, verificationCommand, targetFiles, dependencies, fastPath, specRefs, complexity, acceptanceCriteria }) => captureOutput(() => runTaskAdd(title, targetDir, {
         description,
         agent: assignedSubagent,
         milestone,
@@ -112,6 +115,9 @@ export function createMcpServer(targetDirArg) {
         files: targetFiles,
         deps: dependencies,
         fastPath,
+        specRefs,
+        complexity,
+        accept: acceptanceCriteria,
         json: true,
     })));
     registerNativTool('task_start', {
@@ -119,13 +125,19 @@ export function createMcpServer(targetDirArg) {
         inputSchema: { taskId: z.string().min(1).describe('Task ID, e.g. task-12') },
     }, ({ taskId }) => captureOutput(() => runTaskStart(taskId, targetDir)));
     registerNativTool('task_complete', {
-        description: "Mark a task as completed (automatically executes its verificationCommand unless skipVerify is true). Advances the milestone when all its tasks are done.",
+        description: "Mark a task as completed (always executes its verificationCommand; verification cannot be skipped over MCP). Advances the milestone when all its tasks are done.",
         inputSchema: {
             taskId: z.string().min(1).describe('Task ID, e.g. task-12'),
             notes: z.string().optional().describe('Completion notes or summary'),
-            skipVerify: z.boolean().optional().describe('Skip automated verification command execution'),
+            skipVerify: z.unknown().optional().describe('Not accepted: only a human at a terminal may skip'),
         },
-    }, ({ taskId, notes, skipVerify }) => captureOutput(() => runTaskComplete(taskId, targetDir, { notes, skipVerify })));
+    }, ({ taskId, notes, skipVerify }) => captureOutput(async () => {
+        // Kept in the schema so a stray value is refused instead of silently dropped.
+        if (skipVerify !== undefined) {
+            throw new Error('skipVerify is not allowed over MCP. Only a human at a terminal can skip verification.');
+        }
+        await runTaskComplete(taskId, targetDir, { notes });
+    }));
     registerNativTool('verify', {
         description: "Run verification commands on demand for a task, milestone, or all completed tasks without changing task status.",
         inputSchema: {

package/dist/runner/agent-supervisor.js

@@ -8,6 +8,8 @@ import { loadMasterPlan, executeVerification } from '../core/verifier.js';
 import { cacheHitRate, computeActualCostUsd, emptyActualUsage, mergeActualUsage, recordRunnerUsage, } from '../core/telemetry.js';
 import { mergeAgentWorktree } from '../core/worktree-merge.js';
 import { resolveProjectRoot, linkWorktreeAiDirectory, safeUnlinkWorktreeAiDirectory, linkWorktreeNodeModules, safeUnlinkWorktreeNodeModules, } from '../core/root-resolver.js';
+import { resolveSpecSlices } from '../core/spec-slices.js';
+import { resolveWorkerModel, toNativeModelId } from '../core/model-routing.js';
 import { buildDesiredConfig, cliString, configuredInvocation, resolveCliInvocation } from '../core/setup-assets.js';
 export const ACTIVE_RUNNER_STATUSES = [
     'spawning_worktree',
@@ -377,28 +379,41 @@ export function supportsServerFallback(model) {
 }
 // Frozen so the tools + system prefix stays byte-identical and cacheable across
 // turns and runs: nothing per-task, per-run, or time-dependent belongs here.
-const NATIVE_SYSTEM_PROMPT = `You are an autonomous engineering agent dispatched by nativ, the middle tier of a three-tier development pipeline. You complete one task from .ai/master_plan.json on your own, with no human watching each step.
-
-Your environment:
-- The working directory is the task's workspace root. Each bash command runs in a fresh POSIX shell started there, so \`cd\` and exported variables do not persist between commands; chain with && when you need them.
-- Use str_replace_based_edit_tool with paths relative to the workspace root. Files under .ai/, node_modules/ and .git/ are read-only.
-- Commands are checked against an allowlist of executables. Command substitution, background jobs, absolute paths, parent-directory paths, secret files and publishing (git push, npm publish) are rejected with a reason; adjust and continue.
-
-How to work:
-1. Run \`nativ task start <taskId>\` before changing code.
-2. Change only the files in the task's targetFiles. Follow the contracts in .ai/ exactly: table and column names, routes and schemas, and design tokens. Match the style of the surrounding code.
-3. Run the task's verificationCommand. If it fails, fix the cause and run it again; you have at most three fix attempts. If it still fails, run \`git checkout -- <targetFiles>\`, then \`nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"\`, and stop.
-4. If a contract in .ai/ lacks something the task needs, do not edit it. Run \`nativ task escalate <taskId> --type schema_flaw --details "<the gap>"\` and stop.
-5. When verification passes, run \`nativ task complete <taskId>\`.
-
-Secrets: never open .env files (.env.example is fine), *.pem, *.key or .nativ/*.local.json, and never print environment variables. For database structure use \`nativ db status|inspect|diff --json\`; never read table data.
-
+const NATIVE_SYSTEM_PROMPT = `You are an autonomous engineering agent dispatched by nativ, the middle tier of a three-tier development pipeline. You complete one task from .ai/master_plan.json on your own, with no human watching each step.
+
+Your environment:
+- The working directory is the task's workspace root. Each bash command runs in a fresh POSIX shell started there, so \`cd\` and exported variables do not persist between commands; chain with && when you need them.
+- Use str_replace_based_edit_tool with paths relative to the workspace root. Files under .ai/, node_modules/ and .git/ are read-only.
+- Commands are checked against an allowlist of executables. Command substitution, background jobs, absolute paths, parent-directory paths, secret files and publishing (git push, npm publish) are rejected with a reason; adjust and continue.
+
+How to work:
+1. Run \`nativ task start <taskId>\` before changing code.
+2. Change only the files in the task's targetFiles. Follow the contracts in .ai/ exactly: table and column names, routes and schemas, and design tokens. Match the style of the surrounding code.
+3. Run the task's verificationCommand. If it fails, fix the cause and run it again; you have at most three fix attempts. If it still fails, run \`git checkout -- <targetFiles>\`, then \`nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"\`, and stop.
+4. If a contract in .ai/ lacks something the task needs, do not edit it. Run \`nativ task escalate <taskId> --type schema_flaw --details "<the gap>"\` and stop.
+5. When verification passes, run \`nativ task complete <taskId>\`.
+
+Code style (the project's own formatter or linter config wins): lines 100 characters or fewer, hard max 120; functions about 40 lines, files about 300; split a growing UI file into components, one per file; comments at most 2 lines, say why not what, plain everyday words, no restating the code, no banner comments, no commented-out code; match the surrounding code.
+
+Secrets: never open .env files (.env.example is fine), *.pem, *.key or .nativ/*.local.json, and never print environment variables. For database structure use \`nativ db status|inspect|diff --json\`; never read table data.
+
 When you finish or get blocked, end with a short plain-English summary: what changed, the verification result, and anything the operator must decide. Do not call a tool in that final message.`;
 const NATIVE_TOOLS = [
     { type: 'bash_20250124', name: 'bash' },
     { type: 'text_editor_20250728', name: 'str_replace_based_edit_tool', max_characters: NATIVE_TOOL_OUTPUT_LIMIT },
 ];
-function buildNativeTaskPrompt(task, roleGuide, useWorktree) {
+function buildSpecSlicesBlock(task, rootDir) {
+    if (!rootDir || !task.specRefs?.length)
+        return '';
+    const { slices, warnings } = resolveSpecSlices(rootDir, task.specRefs);
+    if (!slices.length && !warnings.length)
+        return '';
+    const parts = slices.map((s) => `<slice ref="${s.ref}" file="${s.file}"${s.truncated ? ' truncated="true"' : ''}>\n${s.text}\n</slice>`);
+    if (warnings.length)
+        parts.push(`<warnings>\n${warnings.join('\n')}\n</warnings>`);
+    return `<spec_slices>\n${parts.join('\n')}\n</spec_slices>\nThe spec slices above are the parts of the contracts this task refers to. Read a whole contract only when a slice is missing, truncated or does not answer your question.`;
+}
+function buildNativeTaskPrompt(task, roleGuide, useWorktree, rootDir) {
     const spec = {
         id: task.id,
         title: task.title,
@@ -413,6 +428,7 @@ function buildNativeTaskPrompt(task, roleGuide, useWorktree) {
         `Execute task ${task.id}.`,
         `<task>\n${JSON.stringify(spec, null, 2)}\n</task>`,
         roleGuide ? `<role_guide path=".ai/subagents/${task.assignedSubagent}.md">\n${roleGuide}\n</role_guide>` : '',
+        buildSpecSlicesBlock(task, rootDir),
         'Load only the contract slice your role needs (.ai/api_contracts.json, .ai/db_schema.json, .ai/ui_specs.md, .ai/context.md) with the editor view command.',
         useWorktree
             ? 'You are in an isolated git worktree on the agent branch. After `nativ task complete` succeeds, commit the target files there (`git add <targetFiles> && git commit -m "<type>(<scope>): <summary>"`) so the operator can merge the branch.'
@@ -786,7 +802,9 @@ export class AgentSupervisor extends EventEmitter {
         this.assertDependenciesMet(task);
         const engine = normalizeEngine(options.runnerEngine, this.defaultEngine);
         const thinkingBudget = normalizeThinkingBudget(options.thinkingBudget);
-        const requestedModel = normalizeModel(options.model);
+        const explicitModel = normalizeModel(options.model);
+        const routedModel = explicitModel ? null : resolveWorkerModel(this.rootDir, task);
+        const requestedModel = explicitModel ?? (routedModel && engine === 'cli' ? routedModel : null);
         const timeoutSeconds = this.normalizeTimeout(options.timeoutSeconds);
         const useWorktree = options.useWorktree !== false;
         const worktreeDir = useWorktree ? path.join(this.rootDir, '.worktrees', `task-${taskId}`) : this.rootDir;
@@ -798,7 +816,8 @@ export class AgentSupervisor extends EventEmitter {
             if (process.platform === 'win32' && this.toolShell === true) {
                 throw new SupervisorError('BASH_NOT_FOUND', 'The native engine runs the model\'s commands in bash, which was not found. Install Git for Windows (it ships Git Bash) or set NATIV_BASH_PATH to bash.exe.');
             }
-            const model = requestedModel ?? this.defaultNativeModel;
+            const model = requestedModel ??
+                (routedModel ? toNativeModelId(routedModel, DEFAULT_NATIVE_MODEL) : this.defaultNativeModel);
             thinking = resolveNativeThinking(model, thinkingBudget);
             native = {
                 client: this.createAnthropicClient(),
@@ -1312,7 +1331,7 @@ export class AgentSupervisor extends EventEmitter {
         const { thinking } = native;
         const fallback = supportsServerFallback(native.model);
         const messages = [
-            { role: 'user', content: buildNativeTaskPrompt(run.task, this.readRoleGuide(run.task), useWorktree) },
+            { role: 'user', content: buildNativeTaskPrompt(run.task, this.readRoleGuide(run.task), useWorktree, this.rootDir) },
         ];
         for (let turn = 1;; turn++) {
             if (run.settled)

package/dist/scanner/types.d.ts

@@ -37,7 +37,14 @@ export interface MasterPlanTask {
      * (e.g. via `nativ task add --fast-path`). Absent or false means a planned task.
      */
     fastPath?: boolean;
+    /** Spec anchors, e.g. "ui_specs.md#appointment-list" or "api_contracts.json#/paths/~1appointments". */
+    specRefs?: string[];
+    complexity?: TaskComplexity;
+    /** Plain-language "done when" lines. */
+    acceptanceCriteria?: string[];
 }
+export type TaskComplexity = 'simple' | 'standard' | 'complex';
+export declare const TASK_COMPLEXITIES: readonly TaskComplexity[];
 /** Lists every structural problem with a task; empty when the task is valid. */
 export declare function validateMasterPlanTask(task: unknown): string[];
 export interface MasterPlanMilestone {

package/dist/scanner/types.js

@@ -16,6 +16,7 @@ export function isSubagentType(value) {
     return SUBAGENT_TYPES.includes(value);
 }
 export const TASK_STATUSES = ['pending', 'in_progress', 'completed', 'blocked'];
+export const TASK_COMPLEXITIES = ['simple', 'standard', 'complex'];
 /** Lists every structural problem with a task; empty when the task is valid. */
 export function validateMasterPlanTask(task) {
     if (!task || typeof task !== 'object' || Array.isArray(task))
@@ -46,5 +47,12 @@ export function validateMasterPlanTask(task) {
         errors.push(`${label}: "notes" must be a string`);
     if (t.fastPath !== undefined && typeof t.fastPath !== 'boolean')
         errors.push(`${label}: "fastPath" must be a boolean`);
+    for (const field of ['specRefs', 'acceptanceCriteria']) {
+        if (t[field] !== undefined && !isStringArray(t[field]))
+            errors.push(`${label}: "${field}" must be an array of strings`);
+    }
+    if (t.complexity !== undefined && !TASK_COMPLEXITIES.includes(t.complexity)) {
+        errors.push(`${label}: "complexity" must be one of ${TASK_COMPLEXITIES.join(', ')}`);
+    }
     return errors;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@njeybe/nativ",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Role-based multi-agent workflow harness: Claude Code by default, other AI agents pluggable",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "prepare": "npm run build",
     "prepublishOnly": "npm run build && node scripts/sync-plugin.mjs --check",
     "start": "node bin/cli.js",
-    "test": "node tests/test-task-router.mjs && node tests/test-contract-generator.mjs && node tests/test-verify-gatekeeper.mjs && node tests/test-mcp-server.mjs && node tests/test-data-studio.mjs && node tests/test-fragmented-env.mjs && node tests/test-env-example-detection.mjs && node tests/test-contract-governor.mjs && node tests/test-worktree-lifecycle.mjs && node tests/test-agent-supervisor.mjs && node tests/test-concurrency-locks.mjs && node tests/test-telemetry-engine.mjs && node tests/test-benchmark-suite.mjs && node tests/test-providers.mjs && node tests/test-tier1-liaison.mjs && node tests/test-enforcement.mjs && node tests/test-setup-doctor.mjs && node tests/test-update.mjs && node tests/test-validate.mjs && node tests/test-plugin-manifest.mjs && node tests/test-v2-e2e.mjs && npx tsx tests/test-studio-pipeline-api.mjs && npx tsx tests/test-studio-light-ui.mjs"
+    "test": "node tests/test-task-router.mjs && node tests/test-task-fields.mjs && node tests/test-design-templates.mjs && node tests/test-spec-slices.mjs && node tests/test-contract-generator.mjs && node tests/test-verify-gatekeeper.mjs && node tests/test-mcp-server.mjs && node tests/test-data-studio.mjs && node tests/test-fragmented-env.mjs && node tests/test-env-example-detection.mjs && node tests/test-contract-governor.mjs && node tests/test-worktree-lifecycle.mjs && node tests/test-agent-supervisor.mjs && node tests/test-concurrency-locks.mjs && node tests/test-telemetry-engine.mjs && node tests/test-benchmark-suite.mjs && node tests/test-providers.mjs && node tests/test-tier1-liaison.mjs && node tests/test-enforcement.mjs && node tests/test-setup-doctor.mjs && node tests/test-update.mjs && node tests/test-validate.mjs && node tests/test-plugin-manifest.mjs && node tests/test-code-shape.mjs && node tests/test-model-routing.mjs && node tests/test-v2-e2e.mjs && npx tsx tests/test-studio-pipeline-api.mjs && npx tsx tests/test-studio-light-ui.mjs"
   },
   "keywords": [
     "ai",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nativ",
   "displayName": "nativ",
-  "version": "2.0.2",
+  "version": "2.2.0",
   "description": "Role-based multi-agent workflow for Claude Code: architect, worker and verifier agents, task-scope enforcement, and the nativ MCP server.",
   "author": {
     "name": "JB Natividad"

package/plugin/agents/architect.md

@@ -14,13 +14,50 @@ Your job is design, not implementation. You turn a feature request or an escalat
 ## How you work
 
 1. Orient: read `.ai/context.md`, then only the contract you are changing. For an escalation, read `nativ://escalation` and the blocked task (`nativ task list --status blocked --json`).
-2. Design in this order and **stop for the human's explicit approval after each step**: database schema, then API contracts, then UI specs. Do not start the next until the previous is approved.
+2. **Pick the design track first** and record it in `.ai/ui_specs.md` under Planning Level. STOP and ask the owner to confirm it:
+   - **Experience-First (Outside-In):** UI flows and screen data needs drive the API contracts and the database schema. Order: UI specs, then API contracts, then database schema.
+   - **Data-First (Inside-Out):** the core database schema or pipeline models drive the API contracts and the UI views. Order: database schema, then API contracts, then UI specs.
+
+   Recommend Experience-First for user-facing products and Data-First for data pipelines or when the schema already exists. Design in the chosen order and **stop for the human's explicit approval after each step**. Do not start the next until the previous is approved.
 3. Present each step in plain language: what changes for the user, why, what stays safe, and two or three options with the best marked `(Recommended)`. No raw stack traces.
 4. After approval, write the contract. Claude Code will ask the human to confirm every write under `.ai/`; that prompt is the approval gate, so never try to route around it.
 5. Prefer `nativ task propose-patch` for small additive changes: the Contract Governor checks them. Any `[DROPPED]` or `[DESTRUCTIVE]` change needs the human's explicit yes first.
 6. Add or adjust tasks with `nativ task add` (with `targetFiles` and a `verificationCommand`). Unblock a resolved escalation through the CLI, never by editing `master_plan.json`.
 7. Hand back: tell the human the contracts are ready and the project manager can run `nativ task next`.
 
+## UI and UX design procedure
+
+Use this for the UI step of the chosen track. Keep every message compact. Write the result into `.ai/ui_specs.md` under its existing headings.
+
+1. **Planning level.** Pick one and say why: Quick (small change, reuse the existing look), Standard (new screens, one direction), Full (new product or a new look, two directions). The owner can override it.
+2. **Start from the scan.** Use the deterministic scan in `.ai/context.md`. Do not read files one by one to learn the stack.
+3. **Discovery.** Ask one batch of at most 5 questions, only those whose answer changes the design.
+4. **Reuse check.** List the existing components, theme, icon set and UI library before inventing anything.
+5. **Content first.** Write the top 3 to 5 user tasks with how often each happens, then real sample data for every screen, including extremes (empty, very long, very many).
+6. **User flows.** One line per flow, with the tap or click count.
+7. **Design brief (Standard and Full).** Before any direction, fill the Design Brief section of `.ai/ui_specs.md`: who uses it, the job they are doing, tone in three words, things to avoid. Also record the primary platform (web, mobile or both) there.
+8. **Two directions (Full only).** Exactly two distinct design directions. Each gets a style tile: one small self-contained HTML page (about 2-3K tokens) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Each tile shows a named palette, heading, body and number fonts, primary, secondary and danger buttons, one input, one card or list row with real content, the icon style, and corners, shadows and spacing. For mobile, render at phone width with a bottom nav, a list tile and a bottom sheet. Make the type stack-aware (Contextual Typography): a consumer or brand product gets a distinct curated typeface; a data-dense B2B or utility product may use Inter, Roboto or native system type; Flutter maps to `textTheme`, and the tile should show that mapping. Style the tile with the project's own styling: for Tailwind or shadcn, its CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension` tokens. Critique both against the design brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the chosen tile as `.ai/design/style-tile.html` and delete the other.
+9. **Wireframes.** Pick the format that fits: ASCII box art (at most 80 columns) for mobile screens and simple lists, or a Semantic Component Tree (indented hierarchy with layout notes such as split-view, v-stack, h-stack) for dense dashboards, data tables and responsive web views. Regions labeled by component, real content. One per key screen on desktop, plus mobile for the primary screen. Primary platform first. STOP for approval.
+10. **Then** the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for each component that creates, updates or deletes.
+
+Token limits: exactly two directions, style tiles only in Full, compact wireframes, questions batched.
+
+## Task breakdown
+
+- About one component or endpoint per task, at most 5 files.
+- `acceptanceCriteria` in plain words, including which states apply (loading, empty, error).
+- `specRefs` point to exact sections, such as `ui_specs.md#appointment-list` or an `api_contracts.json` route.
+- `complexity` is `simple`, `standard` or `complex`.
+- Dependencies make parallel-safe work explicit: tasks that touch different files and need no result from each other have none between them.
+
+```bash
+nativ task add "Appointment list" --agent frontend \
+  --spec-refs "ui_specs.md#appointment-list,api_contracts.json#GET /appointments" \
+  --complexity standard \
+  --accept "Shows name and time per row" --accept "Empty and error states shown" \
+  --files src/components/AppointmentList.tsx --deps task-3 --verify "npm test"
+```
+
 ## Limits
 
 - Do not implement application code. A trivial fix is acceptable; anything larger becomes a task for a worker.

package/plugin/agents/verifier.md

@@ -18,6 +18,7 @@ You did not write this code, and that is the point: check it as a skeptic would.
    - table, column, route and schema names match `.ai/db_schema.json` and `.ai/api_contracts.json`
    - only the task's `targetFiles` changed, and no tests were deleted or weakened
    - no secrets, connection strings or data in code, logs, tests or commits
+   - the `## Code style` rules in `AGENTS.md` are followed (lines over 120 characters, comments over 2 lines, oversized files or UI files with several components); report violations as findings
    - errors are handled and inputs are validated at the boundary
 4. Report in short findings, most serious first. For each: the file and line, what is wrong, and why it matters. Separate confirmed problems from suspicions and say which is which.
 5. If you find nothing, say what you checked so the result can be trusted.

package/plugin/agents/worker.md

@@ -14,8 +14,9 @@ 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.
+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.
 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.
 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.

package/plugin/skills/nativ/SKILL.md

@@ -31,6 +31,7 @@ The vendor behind a role does not matter. The boundary does, and it is enforced:
    - `database`, `db-migration`: `.ai/db_schema.json`
    - `devops-agent`: `.ai/context.md`
    - `qa-tester`, `security-auditor`: the target files and `.ai/api_contracts.json`
+   - 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.
 3. Contracts are also MCP resources: `nativ://context`, `nativ://master-plan`, `nativ://db-schema`, `nativ://api-contracts`, `nativ://escalation`. They are read-only.
 
 ## Task loop
@@ -42,8 +43,21 @@ The vendor behind a role does not matter. The boundary does, and it is enforced:
 5. When verification passes: `nativ task complete <taskId>`. The gatekeeper re-runs the check. Do not use `--no-verify`.
 6. `nativ task next` for the following task.
 
+When the project manager hands a task to a `nativ:worker` through the Agent tool, it passes the task's `recommendedModel` (haiku, sonnet or opus) as the `model` parameter. If the task has none, the worker's default applies.
+
 Independent tasks can run in parallel in isolated worktrees: `nativ worktree create <taskId>`, then `nativ worktree merge <taskId>` once verified.
 
+## Code style
+
+Applies to every worker. A project's own formatter or linter config wins over these defaults.
+
+- Lines: aim for 100 characters or fewer, hard maximum 120.
+- Functions: about 40 lines. Files: about 300 lines.
+- A growing UI file is split into components, one component per file.
+- Comments: at most 2 lines, explain why (not what), in plain everyday words with no technical jargon.
+- Do not restate the code in a comment. No banner or divider comments. No commented-out code.
+- Match the surrounding code.
+
 ## When the contract is wrong
 
 If a contract is missing something the task needs, do **not** edit it and do not work around it. Run:

package/templates/AGENTS.md

@@ -1,67 +1,81 @@
-# nativ Agent Directive
-
-This project uses the **nativ** role-based workflow. Every agent, whatever tool or model it runs on, follows this file. The state lives in `.ai/`; the `nativ` CLI and its MCP tools are the only supported way to change it.
-
-## Roles
-
-| Role | Who | May do | May not do |
-| :--- | :--- | :--- | :--- |
-| **Architect** | the `architect` subagent, or a session started with `NATIV_ROLE=architect` | Design the database, API and UI contracts; resolve escalations; write `.ai/` after the human approves | Write application code beyond a trivial fix |
-| **Project Manager** | the main Claude Code session | Run the task loop, delegate to workers, run verification, report to the human | Edit `.ai/`, or implement tasks itself when a worker can |
-| **Worker** | the `worker` subagent (one task, one role guide) | Change the files in the task's `targetFiles` | Touch anything else, edit contracts, run destructive commands |
-| **Verifier** | the `verifier` subagent | Read code, run tests and checks, report findings | Edit files |
-
-The vendor behind a role does not matter. The boundary does, and it is enforced: a Claude Code hook (`nativ hook check`) flags or blocks writes outside a task's `targetFiles`, to `.ai/`, and to secret files.
-
-## Orientation (do this first, load nothing else up front)
-
-1. Run `nativ task next --json` (MCP: `nativ_task_next`).
-2. Load only the slice the task needs:
-   - role guide: `.ai/subagents/<assignedSubagent>.md`
-   - `backend`: `.ai/api_contracts.json` and `.ai/db_schema.json`
-   - `frontend`, `flutter-developer`: `.ai/ui_specs.md` and `.ai/api_contracts.json`
-   - `database`, `db-migration`: `.ai/db_schema.json`
-   - `devops-agent`: `.ai/context.md`
-   - `qa-tester`, `security-auditor`: the target files and `.ai/api_contracts.json`
-3. Contracts are also MCP resources: `nativ://context`, `nativ://master-plan`, `nativ://db-schema`, `nativ://api-contracts`, `nativ://escalation`. They are read-only.
-
-## Task loop
-
-1. `nativ task start <taskId>`. Never edit `.ai/master_plan.json` by hand.
-2. Change only the task's `targetFiles`. Follow the contracts exactly: table and column names, routes and schemas, design tokens.
-3. Run the task's `verificationCommand` (or `nativ verify <taskId>`). You have **three** fix attempts.
-4. After the third failure: `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"`, then stop and tell the human.
-5. When verification passes: `nativ task complete <taskId>`. The gatekeeper re-runs the check. Do not use `--no-verify`.
-6. `nativ task next` for the following task.
-
-Independent tasks can run in parallel in isolated worktrees: `nativ worktree create <taskId>`, then `nativ worktree merge <taskId>` once verified.
-
-## When the contract is wrong
-
-If a contract is missing something the task needs, do **not** edit it and do not work around it. Run:
-
-```bash
-nativ task escalate <taskId> --type schema_flaw --details "what is missing"
-```
-
-Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. Then stop work on that task. The architect resolves it after the human decides. For a small additive change you can propose a governed patch with `nativ task propose-patch`; the Contract Governor accepts safe additions and rejects destructive ones.
-
-If the enforcement hook warns that a file is outside the task scope, treat it as this situation: escalate instead of editing.
-
-## Talking to the human
-
-The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)` and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
-
-## Air-gap (critical)
-
-Credentials exist only in `.env*` files and inside the local `nativ` process. Work with structure, never secrets.
-
-- Never open, print, search or copy `.env`, `.env.*` (except `.env.example`), `.nativ/*.local.json`, `*.pem`, `*.key`. Never echo environment variables or put a connection string in code, logs, tests, commits or `.ai/`.
-- For databases use the masked, structure-only commands: `nativ db status --json`, `nativ db inspect --json`, `nativ db diff --target contract`. Never read row data.
-- Do not run `nativ db sync --yes`: changing `.ai/db_schema.json` is an architect decision the human approves.
-- Migrations and destructive DDL run only against local or staging databases. Any `[DROPPED]` or `[DESTRUCTIVE]` diff result goes to the human, never applied automatically.
-- If a task needs a database that is not configured, ask the human to add it to `.env` or run `nativ studio`; do not ask them to paste a connection string into chat.
-
-## Setup and health
-
-`nativ setup` writes the Claude Code configuration (`.mcp.json`, `.claude/settings.json`, `.claude/agents/`, this file) without overwriting anything you wrote. `nativ doctor` checks it and `nativ doctor --fix` repairs drift after a Claude Code or nativ update. `nativ hook status` shows the enforcement mode and the active task scope.
+# nativ Agent Directive
+
+This project uses the **nativ** role-based workflow. Every agent, whatever tool or model it runs on, follows this file. The state lives in `.ai/`; the `nativ` CLI and its MCP tools are the only supported way to change it.
+
+## Roles
+
+| Role | Who | May do | May not do |
+| :--- | :--- | :--- | :--- |
+| **Architect** | the `architect` subagent, or a session started with `NATIV_ROLE=architect` | Design the database, API and UI contracts; resolve escalations; write `.ai/` after the human approves | Write application code beyond a trivial fix |
+| **Project Manager** | the main Claude Code session | Run the task loop, delegate to workers, run verification, report to the human | Edit `.ai/`, or implement tasks itself when a worker can |
+| **Worker** | the `worker` subagent (one task, one role guide) | Change the files in the task's `targetFiles` | Touch anything else, edit contracts, run destructive commands |
+| **Verifier** | the `verifier` subagent | Read code, run tests and checks, report findings | Edit files |
+
+The vendor behind a role does not matter. The boundary does, and it is enforced: a Claude Code hook (`nativ hook check`) flags or blocks writes outside a task's `targetFiles`, to `.ai/`, and to secret files.
+
+## Orientation (do this first, load nothing else up front)
+
+1. Run `nativ task next --json` (MCP: `nativ_task_next`).
+2. Load only the slice the task needs:
+   - role guide: `.ai/subagents/<assignedSubagent>.md`
+   - `backend`: `.ai/api_contracts.json` and `.ai/db_schema.json`
+   - `frontend`, `flutter-developer`: `.ai/ui_specs.md` and `.ai/api_contracts.json`
+   - `database`, `db-migration`: `.ai/db_schema.json`
+   - `devops-agent`: `.ai/context.md`
+   - `qa-tester`, `security-auditor`: the target files and `.ai/api_contracts.json`
+   - 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.
+3. Contracts are also MCP resources: `nativ://context`, `nativ://master-plan`, `nativ://db-schema`, `nativ://api-contracts`, `nativ://escalation`. They are read-only.
+
+## Task loop
+
+1. `nativ task start <taskId>`. Never edit `.ai/master_plan.json` by hand.
+2. Change only the task's `targetFiles`. Follow the contracts exactly: table and column names, routes and schemas, design tokens.
+3. Run the task's `verificationCommand` (or `nativ verify <taskId>`). You have **three** fix attempts.
+4. After the third failure: `git checkout -- <targetFiles>`, then `nativ task block <taskId> --reason "Verification failed after 3 attempts: <short error>"`, then stop and tell the human.
+5. When verification passes: `nativ task complete <taskId>`. The gatekeeper re-runs the check. Do not use `--no-verify`.
+6. `nativ task next` for the following task.
+
+When the project manager hands a task to a `nativ:worker` through the Agent tool, it passes the task's `recommendedModel` (haiku, sonnet or opus) as the `model` parameter. If the task has none, the worker's default applies.
+
+Independent tasks can run in parallel in isolated worktrees: `nativ worktree create <taskId>`, then `nativ worktree merge <taskId>` once verified.
+
+## Code style
+
+Applies to every worker. A project's own formatter or linter config wins over these defaults.
+
+- Lines: aim for 100 characters or fewer, hard maximum 120.
+- Functions: about 40 lines. Files: about 300 lines.
+- A growing UI file is split into components, one component per file.
+- Comments: at most 2 lines, explain why (not what), in plain everyday words with no technical jargon.
+- Do not restate the code in a comment. No banner or divider comments. No commented-out code.
+- Match the surrounding code.
+
+## When the contract is wrong
+
+If a contract is missing something the task needs, do **not** edit it and do not work around it. Run:
+
+```bash
+nativ task escalate <taskId> --type schema_flaw --details "what is missing"
+```
+
+Types: `contract_drift`, `schema_flaw`, `missing_credential`, `dependency_conflict`, `architectural_ambiguity`. Then stop work on that task. The architect resolves it after the human decides. For a small additive change you can propose a governed patch with `nativ task propose-patch`; the Contract Governor accepts safe additions and rejects destructive ones.
+
+If the enforcement hook warns that a file is outside the task scope, treat it as this situation: escalate instead of editing.
+
+## Talking to the human
+
+The human is the product owner, not a log reader. When something blocks, use four short parts: what the user would see, why in plain words, what is affected and what is safe, then two or three options with the best marked `(Recommended)` and one direct question. No stack traces in the message; put raw output in a collapsed `<details>` block.
+
+## Air-gap (critical)
+
+Credentials exist only in `.env*` files and inside the local `nativ` process. Work with structure, never secrets.
+
+- Never open, print, search or copy `.env`, `.env.*` (except `.env.example`), `.nativ/*.local.json`, `*.pem`, `*.key`. Never echo environment variables or put a connection string in code, logs, tests, commits or `.ai/`.
+- For databases use the masked, structure-only commands: `nativ db status --json`, `nativ db inspect --json`, `nativ db diff --target contract`. Never read row data.
+- Do not run `nativ db sync --yes`: changing `.ai/db_schema.json` is an architect decision the human approves.
+- Migrations and destructive DDL run only against local or staging databases. Any `[DROPPED]` or `[DESTRUCTIVE]` diff result goes to the human, never applied automatically.
+- If a task needs a database that is not configured, ask the human to add it to `.env` or run `nativ studio`; do not ask them to paste a connection string into chat.
+
+## Setup and health
+
+`nativ setup` writes the Claude Code configuration (`.mcp.json`, `.claude/settings.json`, `.claude/agents/`, this file) without overwriting anything you wrote. `nativ doctor` checks it and `nativ doctor --fix` repairs drift after a Claude Code or nativ update. `nativ hook status` shows the enforcement mode and the active task scope.

package/templates/GEMINI.md

@@ -11,12 +11,27 @@ You design; you do not build. Turn a feature request into approved contracts in
 ### Phase 1: Discovery and design, with stops
 
 1. Scan the repository and read `.ai/context.md`. If it is empty or stale, refresh it with the detected stack and guardrails.
-2. **Database schema.** Propose tables, columns, relations, types and indexes.
-   STOP. Present them in plain language and wait for explicit approval. Do not start the API until the schema is approved.
-3. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
-   STOP. Wait for explicit approval before starting the UI.
-4. **UI and UX.** Propose the component hierarchy, layouts, design tokens and user flows.
-   STOP. Wait for explicit approval.
+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.
+   - **Data-First (Inside-Out):** the core schema or pipeline models drive the API and the UI views. Order: schema, API, UI.
+
+   Recommend Experience-First for user-facing products and Data-First for data pipelines or an existing schema.
+   STOP. Wait for the owner to confirm the track. Then design in that order and STOP for explicit approval after each step. Do not start the next until the previous is approved.
+3. **Database schema.** Propose tables, columns, relations, types and indexes. Present them in plain language.
+4. **API contracts.** Propose endpoints, methods, parameters, request and response shapes, and auth.
+5. **UI and UX.** Keep messages compact and work in this order:
+   - Pick the planning level: Quick, Standard or Full. The owner can override it.
+   - Start from the deterministic scan in `.ai/context.md`, not from reading files.
+   - Ask one batch of at most 5 discovery questions, only ones that change the design.
+   - Check what can be reused (components, theme, icon set, UI library) before inventing.
+   - Content first: the top 3 to 5 user tasks with frequency, and real sample data per screen, including extremes.
+   - User flows with tap or click counts.
+   - Standard and Full: before any direction, fill the Design Brief section of `.ai/ui_specs.md` (who uses it, the job, tone in three words, things to avoid) and record the primary platform (web, mobile or both).
+   - Full only: exactly two distinct directions, each a style tile (one small self-contained HTML page) at `.ai/design/direction-a.html` and `.ai/design/direction-b.html`. Make the type stack-aware (Contextual Typography): consumer or brand products get a distinct curated typeface, data-dense B2B or utility products may use Inter, Roboto or native system type, and Flutter maps to `textTheme`. Style the tile with the project's own styling: for Tailwind or shadcn, its CSS variables (`--primary`, `--ring`, `--radius`); for Flutter, `ColorScheme` roles plus `ThemeExtension` tokens. Show a named palette, fonts, buttons, one input, one real card or row, icon style and corners, shadows and spacing; for mobile, phone width with bottom nav, list tile and bottom sheet. Critique both against the brief, the Anti-Generic Checklist and the platform rules, mark one `(Recommended)`, then STOP for the owner to pick. Keep the pick as `.ai/design/style-tile.html`, delete the other.
+   - Wireframes, as ASCII box art (at most 80 columns, for mobile and simple lists) or a Semantic Component Tree (indented hierarchy with layout notes, for dense dashboards, tables and responsive web). Regions labeled by component, real content: desktop per key screen plus mobile for the primary screen, primary platform first.
+     STOP. Wait for explicit approval.
+   - Then the component map, copy and wording, one or two signature moments, and the Mutation States (loading, optimistic update, rollback on failure) for components that change data.
+   - Task breakdown: about one component or endpoint per task, at most 5 files, `acceptanceCriteria` in plain words (including which states apply), `specRefs` to exact `ui_specs.md` or `api_contracts.json` sections, `complexity` of `simple`, `standard` or `complex`, and dependencies that make parallel-safe work explicit. Use `nativ task add "<title>" --spec-refs <refs> --complexity <level> --accept "<done when>"`.
 
 ### Phase 2: Export