@njeybe/nativ 2.4.1 → 2.5.1

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.

package/dist/commands/session.d.ts

@@ -1,22 +0,0 @@
-import { SessionCheckpoint, SessionSummaryEntry } from '../core/session-memory.js';
-export interface SessionSaveOptions {
-    summary: string;
-    decision?: string[];
-    obstacle?: string[];
-    next?: string[];
-    activeFiles?: string;
-    task?: string;
-    role?: string;
-    sessionId?: string;
-    json?: boolean;
-}
-export interface SessionListOptions {
-    limit?: number;
-    json?: boolean;
-}
-export interface SessionGetOptions {
-    json?: boolean;
-}
-export declare function runSessionSave(targetDirArg?: string, options?: SessionSaveOptions): Promise<SessionCheckpoint>;
-export declare function runSessionList(targetDirArg?: string, options?: SessionListOptions): Promise<SessionSummaryEntry[]>;
-export declare function runSessionGet(sessionId?: string, targetDirArg?: string, options?: SessionGetOptions): Promise<SessionCheckpoint | null>;

package/dist/commands/session.js

@@ -1,106 +0,0 @@
-import path from 'node:path';
-import pc from 'picocolors';
-import { saveSessionCheckpoint, getLatestSession, getSession, listSessions, } from '../core/session-memory.js';
-export async function runSessionSave(targetDirArg, options = { summary: '' }) {
-    const targetDir = path.resolve(targetDirArg || process.cwd());
-    const files = options.activeFiles
-        ? options.activeFiles.split(',').map((f) => f.trim()).filter(Boolean)
-        : undefined;
-    const checkpoint = saveSessionCheckpoint(targetDir, {
-        sessionId: options.sessionId,
-        summary: options.summary,
-        decisions: options.decision,
-        obstacles: options.obstacle,
-        nextSteps: options.next,
-        activeFiles: files,
-        taskId: options.task,
-        role: options.role,
-    });
-    if (options.json) {
-        console.log(JSON.stringify(checkpoint, null, 2));
-        return checkpoint;
-    }
-    console.log(pc.bold(pc.green(`\n✔ Saved Session Checkpoint: `)) + pc.yellow(`[${checkpoint.sessionId}]`));
-    console.log(pc.bold('  Summary:    ') + pc.white(checkpoint.summary));
-    if (checkpoint.taskId) {
-        console.log(pc.bold('  Task:       ') + pc.yellow(checkpoint.taskId));
-    }
-    if (checkpoint.role) {
-        console.log(pc.bold('  Role:       ') + pc.magenta(checkpoint.role));
-    }
-    if (checkpoint.decisions && checkpoint.decisions.length > 0) {
-        console.log(pc.bold('  Decisions:  ') + pc.dim(checkpoint.decisions.join(' | ')));
-    }
-    if (checkpoint.obstacles && checkpoint.obstacles.length > 0) {
-        console.log(pc.bold('  Obstacles:  ') + pc.red(checkpoint.obstacles.join(' | ')));
-    }
-    if (checkpoint.nextSteps && checkpoint.nextSteps.length > 0) {
-        console.log(pc.bold('  Next Steps: ') + pc.cyan(checkpoint.nextSteps.join(' | ')));
-    }
-    if (checkpoint.activeFiles && checkpoint.activeFiles.length > 0) {
-        console.log(pc.bold('  Files:      ') + pc.dim(checkpoint.activeFiles.join(', ')));
-    }
-    console.log();
-    return checkpoint;
-}
-export async function runSessionList(targetDirArg, options = {}) {
-    const targetDir = path.resolve(targetDirArg || process.cwd());
-    const sessions = listSessions(targetDir, options.limit || 10);
-    if (options.json) {
-        console.log(JSON.stringify(sessions, null, 2));
-        return sessions;
-    }
-    console.log(pc.bold(pc.cyan('\nSession Memory Checkpoints (.ai/memory/sessions/)')));
-    console.log(pc.dim(`Workspace: ${targetDir}\n`));
-    if (sessions.length === 0) {
-        console.log(pc.dim('  No saved sessions found.\n'));
-        console.log(pc.dim('  Save current progress with: ') + pc.white('nativ session save --summary "..."\n'));
-        return sessions;
-    }
-    for (const s of sessions) {
-        const roleTag = s.role ? pc.magenta(`[${s.role}] `) : '';
-        const taskTag = s.taskId ? pc.yellow(`[${s.taskId}] `) : '';
-        console.log(`  ${pc.bold(pc.yellow(s.sessionId))} ${pc.dim(s.timestamp)} ${roleTag}${taskTag}\n    ${pc.white(s.summary)}`);
-    }
-    console.log();
-    return sessions;
-}
-export async function runSessionGet(sessionId, targetDirArg, options = {}) {
-    const targetDir = path.resolve(targetDirArg || process.cwd());
-    const session = sessionId ? getSession(targetDir, sessionId) : getLatestSession(targetDir);
-    if (options.json) {
-        console.log(JSON.stringify(session, null, 2));
-        return session;
-    }
-    if (!session) {
-        console.log(pc.yellow(`\nNo session found${sessionId ? ` matching [${sessionId}]` : ''}.\n`));
-        return null;
-    }
-    console.log(pc.bold(pc.cyan(`\nSession Details: `)) + pc.yellow(`[${session.sessionId}]`));
-    console.log(pc.bold('  Timestamp:  ') + pc.dim(session.timestamp));
-    if (session.taskId)
-        console.log(pc.bold('  Task ID:    ') + pc.yellow(session.taskId));
-    if (session.role)
-        console.log(pc.bold('  Role:       ') + pc.magenta(session.role));
-    console.log(pc.bold('  Summary:    ') + pc.white(session.summary));
-    if (session.decisions && session.decisions.length > 0) {
-        console.log(pc.bold('\n  Key Decisions:'));
-        for (const d of session.decisions)
-            console.log(pc.dim('   • ') + pc.white(d));
-    }
-    if (session.obstacles && session.obstacles.length > 0) {
-        console.log(pc.bold('\n  Obstacles / Blockers:'));
-        for (const o of session.obstacles)
-            console.log(pc.red('   ✖ ') + pc.white(o));
-    }
-    if (session.nextSteps && session.nextSteps.length > 0) {
-        console.log(pc.bold('\n  Next Steps:'));
-        for (const n of session.nextSteps)
-            console.log(pc.cyan('   → ') + pc.white(n));
-    }
-    if (session.activeFiles && session.activeFiles.length > 0) {
-        console.log(pc.bold('\n  Active Files: ') + pc.dim(session.activeFiles.join(', ')));
-    }
-    console.log();
-    return session;
-}

package/dist/core/session-memory.d.ts

@@ -1,42 +0,0 @@
-export interface SessionCheckpoint {
-    sessionId: string;
-    timestamp: string;
-    role?: string;
-    taskId?: string;
-    summary: string;
-    decisions?: string[];
-    obstacles?: string[];
-    nextSteps?: string[];
-    activeFiles?: string[];
-}
-export interface SessionSummaryEntry {
-    sessionId: string;
-    timestamp: string;
-    role?: string;
-    taskId?: string;
-    summary: string;
-}
-export interface SessionIndex {
-    version: '1.0.0';
-    updatedAt: string;
-    latestSessionId?: string;
-    sessions: SessionSummaryEntry[];
-}
-export declare function getSessionMemoryDir(targetDir: string): string;
-export declare function getSessionIndexPath(targetDir: string): string;
-export declare function getLatestSessionPath(targetDir: string): string;
-export declare function loadSessionIndex(targetDir: string): SessionIndex;
-export declare function saveSessionIndex(targetDir: string, index: SessionIndex): void;
-export declare function saveSessionCheckpoint(targetDir: string, input: {
-    sessionId?: string;
-    role?: string;
-    taskId?: string;
-    summary: string;
-    decisions?: string[];
-    obstacles?: string[];
-    nextSteps?: string[];
-    activeFiles?: string[];
-}): SessionCheckpoint;
-export declare function getLatestSession(targetDir: string): SessionCheckpoint | null;
-export declare function getSession(targetDir: string, sessionId: string): SessionCheckpoint | null;
-export declare function listSessions(targetDir: string, limit?: number): SessionSummaryEntry[];

package/dist/core/session-memory.js

@@ -1,121 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-export function getSessionMemoryDir(targetDir) {
-    return path.join(targetDir, '.ai', 'memory', 'sessions');
-}
-export function getSessionIndexPath(targetDir) {
-    return path.join(getSessionMemoryDir(targetDir), 'index.json');
-}
-export function getLatestSessionPath(targetDir) {
-    return path.join(getSessionMemoryDir(targetDir), 'latest.json');
-}
-export function loadSessionIndex(targetDir) {
-    const indexPath = getSessionIndexPath(targetDir);
-    if (!fs.existsSync(indexPath)) {
-        return {
-            version: '1.0.0',
-            updatedAt: new Date().toISOString(),
-            sessions: [],
-        };
-    }
-    try {
-        const raw = fs.readFileSync(indexPath, 'utf8');
-        const parsed = JSON.parse(raw);
-        if (!Array.isArray(parsed.sessions)) {
-            return {
-                version: '1.0.0',
-                updatedAt: new Date().toISOString(),
-                sessions: [],
-            };
-        }
-        return parsed;
-    }
-    catch {
-        return {
-            version: '1.0.0',
-            updatedAt: new Date().toISOString(),
-            sessions: [],
-        };
-    }
-}
-export function saveSessionIndex(targetDir, index) {
-    const dir = getSessionMemoryDir(targetDir);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    index.updatedAt = new Date().toISOString();
-    fs.writeFileSync(getSessionIndexPath(targetDir), JSON.stringify(index, null, 2), 'utf8');
-}
-export function saveSessionCheckpoint(targetDir, input) {
-    const dir = getSessionMemoryDir(targetDir);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    const now = new Date();
-    const dateStr = now.toISOString().replace(/[-:T]/g, '').slice(0, 14);
-    const sessionId = input.sessionId || `sess-${dateStr}`;
-    const checkpoint = {
-        sessionId,
-        timestamp: now.toISOString(),
-        ...(input.role ? { role: input.role.trim() } : {}),
-        ...(input.taskId ? { taskId: input.taskId.trim() } : {}),
-        summary: input.summary.trim(),
-        ...(input.decisions && input.decisions.length > 0 ? { decisions: input.decisions.map((d) => d.trim()) } : {}),
-        ...(input.obstacles && input.obstacles.length > 0 ? { obstacles: input.obstacles.map((o) => o.trim()) } : {}),
-        ...(input.nextSteps && input.nextSteps.length > 0 ? { nextSteps: input.nextSteps.map((n) => n.trim()) } : {}),
-        ...(input.activeFiles && input.activeFiles.length > 0 ? { activeFiles: input.activeFiles.map((f) => f.trim()) } : {}),
-    };
-    // Write individual session file
-    const sessionPath = path.join(dir, `${sessionId}.json`);
-    fs.writeFileSync(sessionPath, JSON.stringify(checkpoint, null, 2), 'utf8');
-    // Write latest.json
-    fs.writeFileSync(getLatestSessionPath(targetDir), JSON.stringify(checkpoint, null, 2), 'utf8');
-    // Update index
-    const index = loadSessionIndex(targetDir);
-    index.latestSessionId = sessionId;
-    // Remove existing entry with same sessionId if updating
-    index.sessions = index.sessions.filter((s) => s.sessionId !== sessionId);
-    index.sessions.unshift({
-        sessionId,
-        timestamp: checkpoint.timestamp,
-        role: checkpoint.role,
-        taskId: checkpoint.taskId,
-        summary: checkpoint.summary,
-    });
-    // Keep index trimmed to 50 most recent sessions
-    if (index.sessions.length > 50) {
-        index.sessions = index.sessions.slice(0, 50);
-    }
-    saveSessionIndex(targetDir, index);
-    return checkpoint;
-}
-export function getLatestSession(targetDir) {
-    const latestPath = getLatestSessionPath(targetDir);
-    if (!fs.existsSync(latestPath)) {
-        return null;
-    }
-    try {
-        const raw = fs.readFileSync(latestPath, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export function getSession(targetDir, sessionId) {
-    const sessionPath = path.join(getSessionMemoryDir(targetDir), `${sessionId}.json`);
-    if (!fs.existsSync(sessionPath)) {
-        return null;
-    }
-    try {
-        const raw = fs.readFileSync(sessionPath, 'utf8');
-        return JSON.parse(raw);
-    }
-    catch {
-        return null;
-    }
-}
-export function listSessions(targetDir, limit = 10) {
-    const index = loadSessionIndex(targetDir);
-    return index.sessions.slice(0, limit);
-}