@lazyingart/agintiflow 0.20.57 → 0.20.59

package/README.md

@@ -47,6 +47,7 @@ Most agent tools are either a chat box with hidden state or an expensive one-mod
 | --- | --- |
 | Cheap intelligence changes the architecture | DeepSeek V4 Flash and Pro make it practical to spend more calls on routing, scouting, review, and recovery instead of forcing one expensive call to do everything. |
 | Inspectable beats mysterious | Plans, tool calls, file diffs, command output, canvas artifacts, and session events are saved and resumable. |
+| Disciplined by default | `AGINTI.md` starts with a behavior contract: surface ambiguity, keep edits surgical, avoid speculative complexity, verify outcomes, and respect permission blockers. |
 | Role-based models | Route, main, spare, wrapper, and auxiliary image roles are separate. You can use cheap route models, stronger main models, optional OpenAI/Qwen/Venice routes, and GRS AI/Venice image tools. |
 | Scouts before big work | Parallel scouts can cheaply map architecture, tests, risks, symbols, and integration points before the main executor edits anything. |
 | SCS for high-risk work | Student-Committee-Supervisor mode adds a typed gate: committee drafts, student approves/monitors, supervisor executes. Use `/scs` or `--scs auto`. |
@@ -64,6 +65,19 @@ aginti init
 aginti
 ```
 
+`aginti init` creates a disciplined `AGINTI.md` by default: project identity, ambiguity protocol, surgical-change policy, verification contract, permission policy, artifact naming, commands, style, and definition of done. For a smaller or domain-specific starting point:
+
+```bash
+aginti init --list-templates
+aginti init --template minimal
+aginti init --template coding
+aginti init --template research
+aginti init --template writing
+aginti init --template design
+aginti init --template aaps
+aginti init --template supervision
+```
+
 On first interactive use, AgInTiFlow opens an auth wizard if no main model key is found. Pick DeepSeek, OpenAI, Qwen, or Venice, paste the key, and it saves to the ignored project-local `.aginti/.env` file with restricted permissions. You can rerun setup any time:
 
 ```bash
@@ -73,6 +87,16 @@ aginti auth venice
 aginti login grsai
 ```
 
+Provider signup and key pages:
+
+| Provider | Register / key page | API base URL used by AgInTiFlow |
+| --- | --- | --- |
+| DeepSeek | [https://platform.deepseek.com/api_keys](https://platform.deepseek.com/api_keys) | `https://api.deepseek.com` |
+| Venice | [https://venice.ai/settings/api](https://venice.ai/settings/api) | `https://api.venice.ai/api/v1` |
+| OpenAI | [https://platform.openai.com/api-keys](https://platform.openai.com/api-keys) | `https://api.openai.com/v1` |
+| Qwen / DashScope | [https://bailian.console.aliyun.com/](https://bailian.console.aliyun.com/) | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` |
+| GRS AI image tools | [https://grsai.ai/dashboard/api-keys](https://grsai.ai/dashboard/api-keys) | Configure with `/auxiliary grsai` or `aginti login grsai` |
+
 Launch the web UI from the same project:
 
 ```bash
@@ -135,6 +159,29 @@ aginti --resume <session-id> \
 
 Permission behavior is intentionally consistent: writes inside the current project are allowed through file tools, network/setup runs are normal in approved Docker workspace mode, and outside-project or trusted-host actions stop with a clear blocker plus a suggested rerun command. See [runtime modes and autonomy](docs/runtime-modes-and-autonomy.md) for the full contract.
 
+## Permission Recipes
+
+Use these when you want explicit control instead of the default interactive policy:
+
+| Mode | Command | What it permits |
+| --- | --- | --- |
+| Strict inspection | `aginti --sandbox-mode docker-readonly --package-install-policy block --allow-shell --no-file-tools --no-web-search "inspect this project without edits"` | Enforced read-only project inspection through shell commands such as `ls`, `rg`, `cat`, and test commands that do not write. No file-tool writes, web calls, workspace writes, or installs. |
+| Full write in current folder | `aginti --sandbox-mode docker-workspace --package-install-policy allow --approve-package-installs --allow-shell --allow-file-tools "build and test this project"` | Read/write inside the current project folder, run network/setup commands in Docker, keep host safer. |
+| Full host computer access | `aginti --sandbox-mode host --package-install-policy allow --approve-package-installs --allow-shell --allow-file-tools --allow-destructive "perform the trusted host maintenance task"` | Direct host shell and destructive actions. Use only when you trust the task and want whole-host access. |
+
+For resume:
+
+```bash
+aginti --resume <session-id> \
+  --sandbox-mode host \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  --allow-destructive \
+  "continue with trusted host access"
+```
+
 ## Real Screenshots
 
 | CLI launch | Web app overview |

package/docs/runtime-modes-and-autonomy.md

@@ -70,6 +70,35 @@ aginti --resume <session-id> \
   "Continue after approval and verify the output was created in this run."
 ```
 
+Three practical permission recipes:
+
+```bash
+# Strict inspection: enforced read-only shell inspection, no file-tool writes, no web, no installs.
+aginti --sandbox-mode docker-readonly \
+  --package-install-policy block \
+  --allow-shell \
+  --no-file-tools \
+  --no-web-search \
+  "inspect this project without edits"
+
+# Full write in the current project folder, with setup commands isolated in Docker.
+aginti --sandbox-mode docker-workspace \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  "build and test this project"
+
+# Full host computer access for trusted maintenance.
+aginti --sandbox-mode host \
+  --package-install-policy allow \
+  --approve-package-installs \
+  --allow-shell \
+  --allow-file-tools \
+  --allow-destructive \
+  "perform the trusted host maintenance task"
+```
+
 For host-only work, use the stricter trusted form deliberately:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lazyingart/agintiflow",
-  "version": "0.20.57",
+  "version": "0.20.59",
   "type": "module",
   "description": "Low-cost, project-aware Web and CLI agents with DeepSeek/Venice/OpenAI routing, visible tool calls, durable sessions, scouts, AAPS, SCS, and guarded local execution.",
   "license": "Apache-2.0",

package/scripts/smoke-capabilities.js

@@ -32,10 +32,43 @@ async function runCli(args, envOverrides = {}) {
   return result.stdout;
 }
 
+async function runCliIn(cwd, args, envOverrides = {}) {
+  const result = await execFileAsync(process.execPath, [path.join(repoRoot, "bin/aginti-cli.js"), ...args], {
+    cwd,
+    timeout: 20000,
+    maxBuffer: 2 * 1024 * 1024,
+    env: {
+      ...process.env,
+      AGINTIFLOW_RUNTIME_DIR: "",
+      AGINTIFLOW_HOME: agintiflowHome,
+      ...envOverrides,
+    },
+  });
+  return result.stdout;
+}
+
 try {
   await runCli(["init"]);
   const agintiMd = await fs.readFile(path.join(tempRoot, "AGINTI.md"), "utf8");
   assert(agintiMd.includes("Project instructions for AgInTiFlow agents."), "init did not create AGINTI.md");
+  assert(agintiMd.includes("## Agent Operating Contract"), "default init did not include the behavior contract");
+  assert(agintiMd.includes("## Verification Contract"), "default init did not include verification contract");
+  assert(agintiMd.includes("## Permission And Safety Contract"), "default init did not include permission contract");
+  assert(agintiMd.includes("## Definition Of Done"), "default init did not include definition of done");
+  const templates = await runCli(["init", "--list-templates"]);
+  assert(templates.includes("disciplined") && templates.includes("supervision"), "init did not list instruction templates");
+  const minimalRoot = path.join(tempRoot, "minimal-template");
+  await fs.mkdir(minimalRoot);
+  const minimalOutput = await runCliIn(minimalRoot, ["init", "--template", "minimal"]);
+  const minimalMd = await fs.readFile(path.join(minimalRoot, "AGINTI.md"), "utf8");
+  assert(minimalOutput.includes("template=minimal"), "minimal init did not report template");
+  assert(minimalMd.includes("## Agent Contract"), "minimal template did not create compact contract");
+  assert(!minimalMd.includes("## Architecture Notes"), "minimal template should stay compact");
+  const codingRoot = path.join(tempRoot, "coding-template");
+  await fs.mkdir(codingRoot);
+  await runCliIn(codingRoot, ["init", "coding"]);
+  const codingMd = await fs.readFile(path.join(codingRoot, "AGINTI.md"), "utf8");
+  assert(codingMd.includes("## Coding Profile Notes"), "coding template did not add coding appendix");
   const capabilities = JSON.parse(await runCli(["capabilities", "--json"]));
   assert(capabilities.project.root === tempRoot, "capabilities did not use cwd as project root");
   assert(capabilities.project.commandCwd === tempRoot, "capabilities did not default commandCwd to project root");
@@ -168,6 +201,7 @@ try {
           "git-policy",
           "skills-capability",
           "env-sandbox-defaults",
+          "aginti-md-contract-templates",
         ],
       },
       null,

package/src/agent-runner.js

@@ -28,6 +28,7 @@ import { captureTmuxPane, listTmuxSessions, sendTmuxKeys, startTmuxSession } fro
 import { languageInstruction } from "./i18n.js";
 import { flushHousekeeping } from "./housekeeping.js";
 import { buildFailedCommandAdvice, buildPermissionAdvice } from "./permission-advice.js";
+import { formatBehaviorContractForPrompt } from "./behavior-contract.js";
 import {
   buildSupervisorInstruction,
   createScsPlan,
@@ -353,6 +354,7 @@ async function createInitialState(config, sessionId) {
           "Avoid destructive actions, purchases, account changes, and sensitive workflows.",
           languageInstruction(config.language || "en"),
           projectInstructionContext,
+          formatBehaviorContractForPrompt(),
           "Treat AGINTI.md as durable project memory and operating instructions for this project. The user can edit it manually or ask you in chat to update it; use workspace file tools for that and never store secrets there.",
           config.allowShellTool
             ? config.useDockerSandbox

package/src/auth-onboarding.js

@@ -41,13 +41,14 @@ export const MAIN_AUTH_PROVIDERS = [
     label: "Qwen",
     keyName: "QWEN_API_KEY",
     description: "Qwen OpenAI-compatible route",
+    keyUrl: "https://bailian.console.aliyun.com/",
   },
   {
     id: "venice",
     label: "Venice",
     keyName: "VENICE_API_KEY",
     description: "Venice OpenAI-compatible text and image routes",
-    keyUrl: "https://venice.ai",
+    keyUrl: "https://venice.ai/settings/api",
   },
 ];
 
@@ -56,6 +57,7 @@ const AUXILIARY_AUTH_PROVIDER = {
   label: "GRS AI / Nano Banana",
   keyName: "GRSAI",
   description: "optional image generation",
+  keyUrl: "https://grsai.ai/dashboard/api-keys",
 };
 
 const AUTH_ALIASES = {

package/src/behavior-contract.js

@@ -0,0 +1,290 @@
+export const INSTRUCTION_TEMPLATE_IDS = [
+  "minimal",
+  "disciplined",
+  "coding",
+  "research",
+  "writing",
+  "design",
+  "aaps",
+  "supervision",
+];
+
+const TEMPLATE_DESCRIPTIONS = {
+  minimal: "Short project memory for tiny or experimental folders.",
+  disciplined: "Default robust agent contract for normal project work.",
+  coding: "Coding-focused contract with commands, tests, style, and architecture notes.",
+  research: "Research-focused contract with sources, reproducibility, and citation notes.",
+  writing: "Writing-focused contract with audience, style, outline, and publication notes.",
+  design: "Design-focused contract with visual system, assets, QA, and artifact notes.",
+  aaps: "AAPS workflow contract with phase criteria, tools, checks, and artifacts.",
+  supervision: "Supervisor/student contract for monitored agent work and evidence gates.",
+};
+
+const TEMPLATE_ALIASES = {
+  default: "disciplined",
+  standard: "disciplined",
+  full: "disciplined",
+  careful: "disciplined",
+  karpathy: "disciplined",
+  code: "coding",
+  dev: "coding",
+  software: "coding",
+  paper: "research",
+  docs: "writing",
+  doc: "writing",
+  article: "writing",
+  visual: "design",
+  ui: "design",
+  workflow: "aaps",
+  student: "supervision",
+  supervise: "supervision",
+};
+
+export function normalizeInstructionTemplate(value = "disciplined", fallback = "disciplined") {
+  const raw = String(value || "").trim().toLowerCase();
+  const normalized = TEMPLATE_ALIASES[raw] || raw;
+  if (INSTRUCTION_TEMPLATE_IDS.includes(normalized)) return normalized;
+  return INSTRUCTION_TEMPLATE_IDS.includes(fallback) ? fallback : "disciplined";
+}
+
+export function listInstructionTemplates() {
+  return INSTRUCTION_TEMPLATE_IDS.map((id) => ({
+    id,
+    description: TEMPLATE_DESCRIPTIONS[id] || "",
+  }));
+}
+
+export function formatInstructionTemplateList() {
+  return listInstructionTemplates()
+    .map((item) => `${item.id.padEnd(12)} ${item.description}`)
+    .join("\n");
+}
+
+export function formatBehaviorContractForPrompt({ mode = "runtime" } = {}) {
+  const prefix = mode === "plan" ? "Planning discipline contract:" : "AgInTiFlow discipline contract:";
+  return [
+    prefix,
+    "Surface ambiguity instead of silently guessing when interpretations change scope, safety, or implementation.",
+    "Prefer the smallest coherent change that satisfies the request; do not add speculative features or abstractions.",
+    "Make surgical edits: no drive-by refactors, unrelated formatting churn, or deletion of code you did not need to touch.",
+    "Define or infer concrete success criteria for non-trivial work, then run focused checks or state why checks are unavailable.",
+    "Respect the permission contract: if a tool is blocked, stop and present the safe rerun/approval path instead of retrying variants.",
+    "Keep artifacts durable and discoverable with descriptive non-conflicting names; never overwrite unless the user clearly asked.",
+  ].join(" ");
+}
+
+export function scsContractCriteria() {
+  return [
+    "Assumptions and ambiguities are explicit enough for the phase.",
+    "The phase is the smallest coherent step toward the user goal.",
+    "The plan avoids speculative features, broad rewrites, and unrelated cleanup.",
+    "The phase has concrete success criteria and an evidence/check path.",
+    "Permission, secret, destructive-action, and artifact-overwrite risks are called out.",
+  ];
+}
+
+function lines(...items) {
+  return items.join("\n");
+}
+
+function baseSections() {
+  return lines(
+    "# AGINTI.md",
+    "",
+    "Project instructions for AgInTiFlow agents.",
+    "",
+    "This file is durable project memory. Edit it directly or ask AgInTiFlow to update it during chat. Keep secrets in `.aginti/.env`, not here.",
+    "",
+    "## Project Identity",
+    "",
+    "- Project name:",
+    "- What this project does:",
+    "- Primary users:",
+    "- Main workflows to preserve:",
+    "- Explicit non-goals:",
+    "",
+    "## Current Priorities",
+    "",
+    "-",
+    "",
+    "## Agent Operating Contract",
+    "",
+    "- Inspect before editing: read this file, relevant README/docs, manifests, entry points, tests, and exact files related to the request.",
+    "- State assumptions when the request is ambiguous. If multiple interpretations would lead to different implementations, ask or present options before editing.",
+    "- Prefer the smallest coherent change that solves the user's actual request.",
+    "- Do not add speculative features, abstractions, configurability, rewrites, or broad refactors unless requested.",
+    "- Do not change adjacent formatting, comments, naming, or style just because it looks improvable.",
+    "- Every changed line should trace to the task or to cleanup caused by the task.",
+    "- Match existing project style even if another style is personally preferable.",
+    "- If you notice unrelated issues, report them separately rather than editing them.",
+    "",
+    "## Verification Contract",
+    "",
+    "For non-trivial work, define success criteria before implementation:",
+    "",
+    "- Target behavior:",
+    "- Files or surfaces likely affected:",
+    "- Verification command(s):",
+    "- Manual checks, if needed:",
+    "",
+    "Preferred loop:",
+    "",
+    "1. Reproduce or inspect the issue.",
+    "2. Make the smallest coherent change.",
+    "3. Run focused checks.",
+    "4. Repair failures caused by the change.",
+    "5. Summarize changed files, checks run, and residual risks.",
+    "",
+    "Do not claim success without a concrete check, unless no check exists and that limitation is stated.",
+    "",
+    "## Permission And Safety Contract",
+    "",
+    "- Current project folder writes are allowed when file tools are enabled.",
+    "- Do not write outside this project unless the user explicitly asks and the runtime permits it.",
+    "- Never print or store secrets in logs, docs, commits, screenshots, or artifacts.",
+    "- Do not edit `.git`, `.env`, dependency caches, generated vendor folders, or large binary files unless explicitly requested.",
+    "- Destructive actions, host maintenance, sudo, publishing, deployment, and broad cleanup require explicit user intent and the appropriate runtime mode.",
+    "- If blocked by policy, stop and suggest the safest rerun command instead of trying command variants.",
+    "",
+    "## File And Artifact Policy",
+    "",
+    "- Use descriptive, non-conflicting filenames for generated docs, stories, images, reports, screenshots, and artifacts.",
+    "- Avoid generic names such as `output.txt`, `story.txt`, or `result.png` unless the user asked for that exact path.",
+    "- Do not overwrite existing files unless the user asked to update, replace, patch, or overwrite them.",
+    "- Keep durable outputs in project folders where the user can find them.",
+    "",
+    "## Commands",
+    "",
+    "- Install:",
+    "- Build:",
+    "- Test:",
+    "- Lint:",
+    "- Typecheck:",
+    "- Format:",
+    "- Preview/run:",
+    "- Deploy/publish:",
+    "",
+    "## Architecture Notes",
+    "",
+    "- Main entry points:",
+    "- Important directories:",
+    "- Generated directories:",
+    "- Files agents should avoid:",
+    "- External services:",
+    "",
+    "## Style And Conventions",
+    "",
+    "- Language/runtime:",
+    "- Package manager:",
+    "- Formatting style:",
+    "- Test framework:",
+    "- Error handling style:",
+    "- Naming conventions:",
+    "",
+    "## Definition Of Done",
+    "",
+    "A task is done when:",
+    "",
+    "- The requested behavior is implemented or the blocker is clearly reported.",
+    "- Relevant checks were run, or missing checks are stated.",
+    "- The diff is scoped to the request.",
+    "- Generated artifacts are named clearly.",
+    "- Git status and residual risks are summarized when relevant."
+  );
+}
+
+function minimalSections() {
+  return lines(
+    "# AGINTI.md",
+    "",
+    "Project instructions for AgInTiFlow agents.",
+    "",
+    "Keep secrets in `.aginti/.env`, not here.",
+    "",
+    "## Project",
+    "",
+    "- Purpose:",
+    "- Important commands:",
+    "- Files or directories to avoid:",
+    "",
+    "## Agent Contract",
+    "",
+    "- Inspect relevant files before editing.",
+    "- Prefer small, surgical changes.",
+    "- Avoid speculative features and broad refactors.",
+    "- Run focused checks when available.",
+    "- Use descriptive non-conflicting filenames for generated outputs."
+  );
+}
+
+function templateAppendix(template) {
+  if (template === "coding") {
+    return lines(
+      "",
+      "## Coding Profile Notes",
+      "",
+      "- Prefer tests or focused repro commands before and after fixes.",
+      "- Keep public APIs stable unless the task explicitly changes them.",
+      "- Check callers before changing shared functions.",
+      "- Record package-manager and test commands as they become known."
+    );
+  }
+  if (template === "research") {
+    return lines(
+      "",
+      "## Research Profile Notes",
+      "",
+      "- Track sources, dates accessed, datasets, assumptions, and limitations.",
+      "- Prefer primary sources and reproducible scripts/notebooks when possible.",
+      "- Separate evidence, interpretation, and speculation."
+    );
+  }
+  if (template === "writing") {
+    return lines(
+      "",
+      "## Writing Profile Notes",
+      "",
+      "- Track audience, tone, outline, publication target, and reference style.",
+      "- Preserve the user's voice; do not over-polish into generic AI prose.",
+      "- Keep drafts, revisions, and final exports clearly named."
+    );
+  }
+  if (template === "design") {
+    return lines(
+      "",
+      "## Design Profile Notes",
+      "",
+      "- Define visual direction, audience, assets, constraints, and acceptance screenshots.",
+      "- Prefer intentional typography, spacing, color, and motion over generic layouts.",
+      "- Save source assets and exported previews with durable names."
+    );
+  }
+  if (template === "aaps") {
+    return lines(
+      "",
+      "## AAPS Profile Notes",
+      "",
+      "- Treat `.aaps` files as top-down workflow specifications.",
+      "- Each phase should list goal, allowed tools, write scope, checks, artifacts, and stop conditions.",
+      "- Validate or compile workflows before reporting success."
+    );
+  }
+  if (template === "supervision") {
+    return lines(
+      "",
+      "## Supervision Profile Notes",
+      "",
+      "- The supervised agent does the actual project work; the supervisor monitors evidence and capability gaps.",
+      "- Verify artifacts directly instead of trusting self-reports.",
+      "- If the student fails due to missing skill/tool/policy, improve AgInTiFlow and resume the same session."
+    );
+  }
+  return "";
+}
+
+export function buildAgintiInstructions(template = "disciplined") {
+  const normalized = normalizeInstructionTemplate(template);
+  const body = normalized === "minimal" ? minimalSections() : `${baseSections()}${templateAppendix(normalized)}`;
+  return `${body}\n`;
+}
+

package/src/cli.js

@@ -35,6 +35,7 @@ import { maybeAutoUpdate } from "./auto-update.js";
 import { readHousekeepingSummary } from "./housekeeping.js";
 import { handleSkillMeshCommand } from "./skillmesh.js";
 import { handleAapsCliCommand } from "./aaps-adapter.js";
+import { formatInstructionTemplateList, normalizeInstructionTemplate } from "./behavior-contract.js";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -404,7 +405,7 @@ export function parseArgs(argv) {
 
 function printUsage() {
   console.log(
-    'Usage: aginti [chat] OR aginti web [--port 3210] OR aginti update OR aginti models OR aginti aaps [status|init|files|validate|compile|check|run] OR aginti skills [query] OR aginti skillmesh [status|off|record|share|sync|serve|service] OR aginti housekeeping [--json] OR aginti auth [deepseek|openai|qwen|venice|grsai] OR aginti resume [--all-sessions] [latest|<session-id>] ["prompt"] OR aginti --remove-empty-sessions OR aginti --remove-sessions OR aginti queue <session-id> "message" OR aginti [--no-auto-update] [--language en|ja|zh-Hans|zh-Hant|ko|fr|es|ar|vi|de|ru] [--image] [--latex] [--scs|--scs auto|--no-scs] [--routing smart|fast|complex|manual] [--provider deepseek|openai|qwen|venice|mock] [--model MODEL] [--route-model MODEL] [--main-model MODEL] [--spare-model MODEL --spare-reasoning medium] [--aux-provider grsai|venice --aux-model MODEL] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex --wrapper-model gpt-5.5] [--list-models|--list-routes] "your task"'
+    'Usage: aginti [chat] OR aginti init [--template minimal|disciplined|coding|research|writing|design|aaps|supervision] OR aginti web [--port 3210] OR aginti update OR aginti models OR aginti aaps [status|init|files|validate|compile|check|run] OR aginti skills [query] OR aginti skillmesh [status|off|record|share|sync|serve|service] OR aginti housekeeping [--json] OR aginti auth [deepseek|openai|qwen|venice|grsai] OR aginti resume [--all-sessions] [latest|<session-id>] ["prompt"] OR aginti --remove-empty-sessions OR aginti --remove-sessions OR aginti queue <session-id> "message" OR aginti [--no-auto-update] [--language en|ja|zh-Hans|zh-Hant|ko|fr|es|ar|vi|de|ru] [--image] [--latex] [--scs|--scs auto|--no-scs] [--routing smart|fast|complex|manual] [--provider deepseek|openai|qwen|venice|mock] [--model MODEL] [--route-model MODEL] [--main-model MODEL] [--spare-model MODEL --spare-reasoning medium] [--aux-provider grsai|venice --aux-model MODEL] [--sandbox-mode host|docker-readonly|docker-workspace] [--package-install-policy block|prompt|allow] [--approve-package-installs] [--allow-shell|--no-shell] [--allow-file-tools|--no-file-tools] [--web-search|--no-web-search] [--parallel-scouts|--no-parallel-scouts --scout-count 1..10] [--allow-auxiliary-tools|--no-auxiliary-tools] [--allow-wrappers --wrapper codex --wrapper-model gpt-5.5] [--list-models|--list-routes] "your task"'
   );
   console.log(`Languages: ${["en", "ja", "zh-Hans", "zh-Hant", "ko", "fr", "es", "ar", "vi", "de", "ru"].map((code) => `${code}=${languageLabel(code)}`).join(", ")}`);
 }
@@ -585,11 +586,34 @@ async function printHousekeeping(argv = []) {
 function printInitResult(result) {
   console.log(`AgInTiFlow project initialized: ${result.projectRoot}`);
   console.log(`instructions=${result.instructionsPath}`);
+  if (result.template) console.log(`template=${result.template}`);
   console.log(`control=${result.controlDir}`);
   console.log(`projectSessions=${result.sessionsDir}`);
   console.log(`created=${result.created.length} updated=${result.updated.length} skipped=${result.skipped.length}`);
 }
 
+function parseInitOptions(argv = []) {
+  let template = "disciplined";
+  let list = false;
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (arg === "--template" || arg === "-t") {
+      template = readOption(argv, index) || template;
+      index += 1;
+      continue;
+    }
+    if (arg === "--list-templates" || arg === "templates" || arg === "list") {
+      list = true;
+      continue;
+    }
+    if (!arg.startsWith("-")) template = arg;
+  }
+  return {
+    template: normalizeInstructionTemplate(template),
+    list,
+  };
+}
+
 function printDoctorReport(report) {
   console.log(`AgInTiFlow ${report.package.version} (npm latest: ${report.package.npmLatest})`);
   console.log(`node=${report.node.version} ok=${report.node.ok}`);
@@ -1101,66 +1125,73 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  if (argv.includes("--remove-empty-sessions") || argv[0] === "remove-empty-sessions") {
+  if (commandArgv.includes("--remove-empty-sessions") || commandArgv[0] === "remove-empty-sessions") {
     await handleRemoveSessionsCommand({ emptyOnly: true });
     return;
   }
 
-  if (argv.includes("--remove-sessions") || argv[0] === "remove-sessions") {
+  if (commandArgv.includes("--remove-sessions") || commandArgv[0] === "remove-sessions") {
     await handleRemoveSessionsCommand({ emptyOnly: false });
     return;
   }
 
-  if (argv[0] === "init") {
-    printInitResult(await initProject(process.cwd()));
+  if (commandArgv[0] === "init") {
+    const initOptions = parseInitOptions(commandArgv.slice(1));
+    if (initOptions.list) {
+      console.log(formatInstructionTemplateList());
+      return;
+    }
+    printInitResult(await initProject(commandCwd, { template: initOptions.template }));
     return;
   }
 
-  if (argv[0] === "doctor") {
-    const parsed = parseArgs(argv.slice(1).filter((arg) => arg !== "--json" && arg !== "--capabilities"));
+  if (commandArgv[0] === "doctor") {
+    const parsed = parseArgs(commandArgv.slice(1).filter((arg) => arg !== "--json" && arg !== "--capabilities"));
     const config = loadConfig(
       {
         ...parsed,
         goal: "doctor",
+        commandCwd,
         allowShellTool: parsed.allowShellTool ?? true,
         allowFileTools: parsed.allowFileTools ?? true,
       },
-      { packageDir, baseDir: process.cwd() }
+      { packageDir, baseDir: commandCwd }
     );
-    const report = argv.includes("--capabilities")
-      ? await buildCapabilityReport(process.cwd(), packageJson.version, config)
-      : await doctorReport(process.cwd(), packageJson.version, config);
-    if (argv.includes("--json")) console.log(JSON.stringify(report, null, 2));
-    else if (argv.includes("--capabilities")) printCapabilityReport(report);
+    const report = commandArgv.includes("--capabilities")
+      ? await buildCapabilityReport(commandCwd, packageJson.version, config)
+      : await doctorReport(commandCwd, packageJson.version, config);
+    if (commandArgv.includes("--json")) console.log(JSON.stringify(report, null, 2));
+    else if (commandArgv.includes("--capabilities")) printCapabilityReport(report);
     else printDoctorReport(report);
     return;
   }
 
-  if (argv[0] === "capabilities") {
-    const parsed = parseArgs(argv.slice(1).filter((arg) => arg !== "--json"));
+  if (commandArgv[0] === "capabilities") {
+    const parsed = parseArgs(commandArgv.slice(1).filter((arg) => arg !== "--json"));
     const config = loadConfig(
       {
         ...parsed,
         goal: "capabilities",
+        commandCwd,
         allowShellTool: parsed.allowShellTool ?? true,
         allowFileTools: parsed.allowFileTools ?? true,
       },
-      { packageDir, baseDir: process.cwd() }
+      { packageDir, baseDir: commandCwd }
     );
-    const report = await buildCapabilityReport(process.cwd(), packageJson.version, config);
-    if (argv.includes("--json")) console.log(JSON.stringify(report, null, 2));
+    const report = await buildCapabilityReport(commandCwd, packageJson.version, config);
+    if (commandArgv.includes("--json")) console.log(JSON.stringify(report, null, 2));
     else printCapabilityReport(report);
     return;
   }
 
-  if (argv[0] === "housekeeping" || argv[0] === "housekeeper") {
-    await printHousekeeping(argv.slice(1));
+  if (commandArgv[0] === "housekeeping" || commandArgv[0] === "housekeeper") {
+    await printHousekeeping(commandArgv.slice(1));
     return;
   }
 
-  if (argv[0] === "skillmesh" || argv[0] === "skillsync" || argv[0] === "skill-sync" || argv[0] === "skill-share") {
+  if (commandArgv[0] === "skillmesh" || commandArgv[0] === "skillsync" || commandArgv[0] === "skill-sync" || commandArgv[0] === "skill-share") {
     try {
-      await handleSkillMeshCommand(argv.slice(1));
+      await handleSkillMeshCommand(commandArgv.slice(1));
     } catch (error) {
       console.error(error instanceof Error ? error.message : String(error));
       process.exit(1);
@@ -1168,63 +1199,63 @@ export async function main(argv = process.argv.slice(2)) {
     return;
   }
 
-  if (argv[0] === "keys/status") {
+  if (commandArgv[0] === "keys/status") {
     await handleKeyCommand(["status"]);
     return;
   }
 
-  if (argv[0] === "keys") {
-    await handleKeyCommand(argv.slice(1));
+  if (commandArgv[0] === "keys") {
+    await handleKeyCommand(commandArgv.slice(1));
     return;
   }
 
-  if (argv[0] === "auth" || argv[0] === "login") {
-    const provider = normalizeAuthProvider(argv[1] || "", "");
-    if (argv[0] === "auth" || (!provider && process.stdin.isTTY)) {
-      const result = await runAuthWizard(process.cwd(), { provider });
+  if (commandArgv[0] === "auth" || commandArgv[0] === "login") {
+    const provider = normalizeAuthProvider(commandArgv[1] || "", "");
+    if (commandArgv[0] === "auth" || (!provider && process.stdin.isTTY)) {
+      const result = await runAuthWizard(commandCwd, { provider });
       printAuthWizardResult(result);
       return;
     }
     const target = provider || "deepseek";
-    const key = argv.includes("--stdin") || !process.stdin.isTTY
+    const key = commandArgv.includes("--stdin") || !process.stdin.isTTY
       ? await readStdin()
       : await promptHidden(`${providerLabel(target)} API key/token: `);
     if (!key) {
       console.error("No key saved.");
       process.exit(1);
     }
-    const result = await setProviderKey(process.cwd(), target, key);
+    const result = await setProviderKey(commandCwd, target, key);
     console.log(`saved ${result.provider} key to project-local ignored env (${result.keyName})`);
     return;
   }
 
-  if (argv[0] === "sessions") {
-    await handleSessionsCommand(argv.slice(1));
+  if (commandArgv[0] === "sessions") {
+    await handleSessionsCommand(commandArgv.slice(1));
     return;
   }
 
-  if (argv[0] === "storage") {
-    await handleStorageCommand(argv.slice(1));
+  if (commandArgv[0] === "storage") {
+    await handleStorageCommand(commandArgv.slice(1));
     return;
   }
 
-  if (argv[0] === "models" || argv[0] === "model") {
+  if (commandArgv[0] === "models" || commandArgv[0] === "model") {
     printModels();
     return;
   }
 
-  if (argv[0] === "skills" || argv[0] === "skill") {
-    printSkills(argv.slice(1).join(" ").trim());
+  if (commandArgv[0] === "skills" || commandArgv[0] === "skill") {
+    printSkills(commandArgv.slice(1).join(" ").trim());
     return;
   }
 
-  if (argv[0] === "queue") {
-    await handleQueueCommand(argv.slice(1));
+  if (commandArgv[0] === "queue") {
+    await handleQueueCommand(commandArgv.slice(1));
     return;
   }
 
-  if (argv[0] === "resume") {
-    const resumeArgv = argv.slice(1);
+  if (commandArgv[0] === "resume") {
+    const resumeArgv = commandArgv.slice(1);
     const allSessions = resumeArgv.includes("--all-sessions");
     const positional = resumeArgv.filter((arg) => arg !== "--all-sessions");
     let sessionId = positional[0] || "";
@@ -1237,20 +1268,20 @@ export async function main(argv = process.argv.slice(2)) {
     }
     if (!sessionId) return;
     if (!prompt) {
-      await startInteractiveCli(agentDefaults({ ...parseArgs([]), resume: sessionId }), {
+      await startInteractiveCli(agentDefaults({ ...parseArgs([]), resume: sessionId, commandCwd }), {
         packageDir,
         packageVersion: packageJson.version,
       });
       return;
     }
-    const resumeArgs = agentDefaults({ ...parseArgs([prompt]), resume: sessionId, goal: prompt });
+    const resumeArgs = agentDefaults({ ...parseArgs([prompt]), resume: sessionId, goal: prompt, commandCwd });
     if (!(await ensureDeepSeekKeyForOneShot(resumeArgs))) process.exit(1);
     const config = loadConfig(resumeArgs, { packageDir });
     await runAgent(config);
     return;
   }
 
-  const args = parseArgs(argv);
+  const args = { ...parseArgs(commandArgv), commandCwd };
 
   if (args.web) {
     if (args.port) process.env.PORT = String(args.port);

package/src/interactive-cli.js

@@ -35,6 +35,7 @@ import {
 } from "./skillmesh.js";
 import { normalizeScsMode } from "./scs-controller.js";
 import { formatAapsResult, runAapsAction } from "./aaps-adapter.js";
+import { formatInstructionTemplateList, normalizeInstructionTemplate } from "./behavior-contract.js";
 
 const useColor = Boolean(input.isTTY && output.isTTY && process.env.AGINTIFLOW_NO_COLOR !== "1");
 const ansi = {
@@ -108,6 +109,12 @@ const SLASH_COMMANDS = [
   "/web",
   "/exit",
 ];
+
+function parseInitTemplateValue(value = "") {
+  const parts = String(value || "").trim().split(/\s+/).filter(Boolean);
+  if (parts[0] === "template" || parts[0] === "--template" || parts[0] === "-t") return normalizeInstructionTemplate(parts[1]);
+  return normalizeInstructionTemplate(parts[0] || "disciplined");
+}
 const promptHistory = [];
 let activeRunInput = null;
 let cliLanguage = resolveLanguage();
@@ -2565,9 +2572,14 @@ async function handleCommand(line, state, packageDir) {
     return true;
   }
   if (command === "instructions" || command === "memory") {
-    if (value === "init") {
-      const result = await initProject(process.cwd());
-      printAgentMessage(`AGINTI.md ready at ${result.instructionsPath}`);
+    if (value === "templates") {
+      printAgentMessage(`Available AGINTI.md templates:\n${formatInstructionTemplateList()}`);
+      return true;
+    }
+    if (value === "init" || value.startsWith("init ")) {
+      const template = parseInitTemplateValue(value.replace(/^init\b\s*/, ""));
+      const result = await initProject(process.cwd(), { template });
+      printAgentMessage(`AGINTI.md ready at ${result.instructionsPath}\ntemplate=${result.template}`);
       return true;
     }
     const instructions = await readProjectInstructions(process.cwd(), { maxBytes: 4000 });
@@ -3079,8 +3091,13 @@ async function handleCommand(line, state, packageDir) {
     return true;
   }
   if (command === "init") {
-    const result = await initProject(process.cwd());
-    printAgentMessage(`initialized project=${result.projectRoot}\nAGINTI.md=${result.instructionsPath}`);
+    if (value === "templates" || value === "list") {
+      printAgentMessage(`Available AGINTI.md templates:\n${formatInstructionTemplateList()}`);
+      return true;
+    }
+    const template = parseInitTemplateValue(value);
+    const result = await initProject(process.cwd(), { template });
+    printAgentMessage(`initialized project=${result.projectRoot}\nAGINTI.md=${result.instructionsPath}\ntemplate=${result.template}`);
     return true;
   }
   if (command === "web") {

package/src/model-client.js

@@ -5,6 +5,7 @@ import { listAuxiliarySkills } from "./auxiliary-tools.js";
 import { engineeringGuidanceForTask } from "./engineering-guidance.js";
 import { formatSkillsForPrompt, selectSkillsForGoal } from "./skill-library.js";
 import { platformInfo, platformLabel } from "./platform.js";
+import { formatBehaviorContractForPrompt } from "./behavior-contract.js";
 
 export function createClient(config) {
   if (config.provider === "mock") {
@@ -498,7 +499,7 @@ export async function createPlan(client, config, state) {
       {
         role: "system",
         content:
-          "You are planning a browser, shell, workspace, and coding-agent task. The plan is only a launchpad: after planning, the runtime will continue with tools until the task is complete or genuinely blocked. Prefer real workspace edits/checks over advice-only answers. If a local shell command can satisfy the goal, prefer that before browser actions. Treat any suggested start URL as optional. Write a concise execution plan with 3 to 6 steps. Mention risks or blockers when relevant. Keep it short and practical.",
+          `You are planning a browser, shell, workspace, and coding-agent task. The plan is only a launchpad: after planning, the runtime will continue with tools until the task is complete or genuinely blocked. Prefer real workspace edits/checks over advice-only answers. If a local shell command can satisfy the goal, prefer that before browser actions. Treat any suggested start URL as optional. ${formatBehaviorContractForPrompt({ mode: "plan" })} Write a concise execution plan with 3 to 6 steps. Mention risks or blockers when relevant. Keep it short and practical.`,
       },
       {
         role: "user",

package/src/project.js

@@ -6,6 +6,7 @@ import { promisify } from "node:util";
 import { listAgentWrappers } from "./tool-wrappers.js";
 import { getDockerSandboxStatus } from "./docker-sandbox.js";
 import { platformInfo, platformLabel, platformSetupHints } from "./platform.js";
+import { buildAgintiInstructions, normalizeInstructionTemplate } from "./behavior-contract.js";
 import {
   LEGACY_PROJECT_SESSIONS_DIR_NAME,
   PROJECT_SESSIONS_DIR_NAME,
@@ -157,35 +158,8 @@ export async function ensureProjectSessionStorage(projectRoot = process.cwd()) {
   return paths;
 }
 
-export function defaultAgintiInstructions() {
-  return [
-    "# AGINTI.md",
-    "",
-    "Project instructions for AgInTiFlow agents.",
-    "",
-    "Edit this file directly or ask AgInTiFlow to update it during chat. Keep durable project preferences here; keep secrets in `.aginti/.env` instead.",
-    "",
-    "## Project Goals",
-    "",
-    "- Describe what this project is for.",
-    "- Note the main user-facing workflows the agent should preserve.",
-    "",
-    "## Agent Preferences",
-    "",
-    "- Prefer small, inspectable changes over broad rewrites.",
-    "- Read relevant files before editing.",
-    "- Run focused checks when tools and dependencies are available.",
-    "- Keep generated artifacts in project folders with clear names.",
-    "",
-    "## Useful Commands",
-    "",
-    "- Add build, test, lint, preview, or compile commands here.",
-    "",
-    "## Notes",
-    "",
-    "- Add project-specific terminology, style preferences, and known constraints here.",
-    "",
-  ].join("\n");
+export function defaultAgintiInstructions(template = "disciplined") {
+  return buildAgintiInstructions(template);
 }
 
 export async function readProjectInstructions(projectRoot = process.cwd(), { maxBytes = 24_000 } = {}) {
@@ -272,8 +246,9 @@ async function ensureLine(filePath, lines) {
   return { changed: true, path: filePath, added: missing };
 }
 
-export async function initProject(projectRoot = process.cwd()) {
+export async function initProject(projectRoot = process.cwd(), { template = "disciplined" } = {}) {
   const paths = projectPaths(projectRoot);
+  const instructionTemplate = normalizeInstructionTemplate(template);
   const created = [];
   const updated = [];
   const skipped = [];
@@ -300,7 +275,7 @@ export async function initProject(projectRoot = process.cwd()) {
   await fsp.mkdir(paths.globalSessionsDir, { recursive: true });
   await ensureFile(
     paths.agintiInstructionsPath,
-    defaultAgintiInstructions()
+    defaultAgintiInstructions(instructionTemplate)
   );
   await ensureFile(
     paths.controlReadmePath,
@@ -370,6 +345,7 @@ export async function initProject(projectRoot = process.cwd()) {
     created,
     updated,
     skipped,
+    template: instructionTemplate,
   };
 }
 

package/src/scs-controller.js

@@ -1,4 +1,5 @@
 import { redactSensitiveText, redactValue } from "./redaction.js";
+import { formatBehaviorContractForPrompt, scsContractCriteria } from "./behavior-contract.js";
 
 export const SCS_MODES = ["off", "on", "auto"];
 
@@ -67,9 +68,10 @@ export function shouldActivateScs(mode = "off", context = {}) {
 function fallbackPlan(goal = "") {
   return [
     "1. Inspect the workspace, project instructions, and relevant manifests before editing.",
-    "2. Make the smallest coherent implementation or research pass that satisfies the request.",
-    "3. Run targeted checks or document why checks are unavailable.",
-    "4. Finish only after concrete evidence supports the result.",
+    "2. State assumptions or ambiguities that could change scope, safety, or implementation.",
+    "3. Make the smallest coherent implementation or research pass that satisfies the request.",
+    "4. Run targeted checks or document why checks are unavailable.",
+    "5. Finish only after concrete evidence supports the result.",
   ].join("\n");
 }
 
@@ -207,6 +209,7 @@ export function buildSupervisorInstruction(scs = {}) {
   return [
     "SCS mode is enabled. You are the supervisor executor.",
     "Execute the approved phase plan. You may choose exact tools and paths, but you may not replace the strategic plan with a new one.",
+    formatBehaviorContractForPrompt(),
     "If tool evidence invalidates the plan, stop repeating the failed path and explain the blocker through finish or wait for student review.",
     "Approved phase plan:",
     scs.plan || fallbackPlan(),
@@ -225,6 +228,7 @@ function normalizeCommitteePlan(parsed, goal = "") {
     phaseGoal: compact(parsed.phase_goal || parsed.phaseGoal || goal || "Complete the requested task.", 260),
     plan,
     acceptanceCriteria: normalizeStringList(parsed.acceptance_criteria || parsed.acceptanceCriteria, [
+      ...scsContractCriteria(),
       "The requested outcome is present in the workspace or answer.",
       "Relevant checks were run or skipped with a concrete reason.",
     ]),
@@ -280,7 +284,7 @@ export async function createScsPlan(client, config, state, context = {}) {
         {
           role: "system",
           content:
-            "You are the SCS committee. Draft one practical next-phase plan only. You cannot approve it and you cannot call tools. Return strict JSON with keys: role, phase_goal, plan, acceptance_criteria, allowed_tools, stop_conditions.",
+            `You are the SCS committee. Draft one practical next-phase plan only. You cannot approve it and you cannot call tools. ${formatBehaviorContractForPrompt({ mode: "plan" })} Return strict JSON with keys: role, phase_goal, plan, acceptance_criteria, allowed_tools, stop_conditions.`,
         },
         {
           role: "user",
@@ -299,7 +303,7 @@ export async function createScsPlan(client, config, state, context = {}) {
         {
           role: "system",
           content:
-            "You are the SCS student monitor. You may approve_plan or veto_plan only. Judge whether the committee phase plan is safe, concrete, and evidence-oriented. Return strict JSON with keys: role, decision, confidence, evidence, reason, next_required_action.",
+            `You are the SCS student monitor. You may approve_plan or veto_plan only. Judge whether the committee phase plan is safe, scoped, minimal, permission-aware, and evidence-oriented. ${formatBehaviorContractForPrompt({ mode: "plan" })} Return strict JSON with keys: role, decision, confidence, evidence, reason, next_required_action.`,
         },
         {
           role: "user",