@rosetears/aili-pi 0.1.0

package/scripts/sync-skills.ts

@@ -0,0 +1,356 @@
+import { createHash } from "node:crypto";
+import {
+  cp,
+  lstat,
+  mkdir,
+  readdir,
+  readFile,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import { basename, dirname, relative, resolve, sep } from "node:path";
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const SNAPSHOT = resolve(ROOT, "skills");
+const LOCK = resolve(ROOT, "upstream/aili-workflows.lock.json");
+const COMPATIBILITY = resolve(ROOT, "manifests/skill-compatibility.json");
+const REPOSITORY = "https://github.com/Rosetears520/aili-workflows.git";
+
+type FileRecord = { path: string; sha256: string; bytes: number };
+type AnchorRecord = {
+  id: string;
+  disposition: string;
+  occurrences: Array<{ path: string; lines: number[] }>;
+};
+
+interface LockFile {
+  schemaVersion: 1;
+  repository: string;
+  commit: string;
+  repositoryTree: string;
+  skillTree: string;
+  skillRoot: ".agents/skills";
+  skillCount: number;
+  fileCount: number;
+  contentHash: string;
+  synchronizedAt: string;
+  files: FileRecord[];
+  skills: Array<{ name: string; sourceHash: string; files: string[] }>;
+}
+
+const anchorPatterns = [
+  {
+    id: "backend.opencode",
+    pattern: /\bopencode\b|\.opencode\/|~\/\.config\/opencode\//gi,
+    disposition: "retained as current adapter evidence; Pi must map the capability",
+  },
+  {
+    id: "tool.subagent",
+    pattern: /\bTask\b|task_id|subagent_type|subagent\.dispatch/gi,
+    disposition: "mapped through subagent.dispatch or blocked",
+  },
+  {
+    id: "tool.browser",
+    pattern: /playwright_|Playwright MCP|Chrome DevTools MCP|browser\.qa/gi,
+    disposition: "mapped through browser.qa or optional",
+  },
+  {
+    id: "tool.symbol-graph",
+    pattern: /\bCodeGraph\b|codegraph_|\bGraphify\b/gi,
+    disposition: "mapped through repository graph capabilities or optional",
+  },
+  {
+    id: "backend.openspec",
+    pattern: /\bOpenSpec\b|openspec\//gi,
+    disposition: "retained as an artifact backend contract; no completion authority",
+  },
+  {
+    id: "path.backend-home",
+    pattern: /~\/\.agents\/|~\/\.pi\/|\.config\/opencode/gi,
+    disposition: "must resolve through the active adapter or remain blocked",
+  },
+  {
+    id: "external.side-effect",
+    pattern: /\b(download|install|publish|release|upload|network|credential|secret)\b/gi,
+    disposition: "retained behind explicit capability and operation gates",
+  },
+] as const;
+
+function sha256(content: Buffer | string): string {
+  return createHash("sha256").update(content).digest("hex");
+}
+
+function posixPath(path: string): string {
+  return path.split(sep).join("/");
+}
+
+function git(source: string, args: string[]): string {
+  return execFileSync("git", ["-C", source, ...args], { encoding: "utf8" }).trim();
+}
+
+async function collectFiles(root: string): Promise<FileRecord[]> {
+  const records: FileRecord[] = [];
+
+  async function visit(directory: string): Promise<void> {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+      const absolute = resolve(directory, entry.name);
+      const metadata = await lstat(absolute);
+      if (metadata.isSymbolicLink()) {
+        throw new Error(`symbolic links are not allowed in the skill snapshot: ${absolute}`);
+      }
+      if (metadata.isDirectory()) {
+        await visit(absolute);
+      } else if (metadata.isFile()) {
+        const content = await readFile(absolute);
+        records.push({
+          path: posixPath(relative(root, absolute)),
+          sha256: sha256(content),
+          bytes: content.byteLength,
+        });
+      }
+    }
+  }
+
+  await visit(root);
+  return records.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function aggregateHash(files: FileRecord[]): string {
+  return sha256(files.map((file) => `${file.path}\0${file.sha256}\0${file.bytes}\n`).join(""));
+}
+
+function skillHash(files: FileRecord[]): string {
+  return aggregateHash(files);
+}
+
+function parseDescription(markdown: string): string {
+  const match = markdown.match(/^---\s*\n[\s\S]*?^description:\s*(.+)$/m);
+  return match?.[1]?.trim() ?? "Unverified: frontmatter description was not parsed";
+}
+
+function stopOutcomes(markdown: string): string[] {
+  return ["complete", "need-user", "need-evidence", "material-delta", "blocked", "Unverified"]
+    .filter((outcome) => markdown.includes(outcome));
+}
+
+function textContent(content: Buffer): string | undefined {
+  if (content.includes(0)) return undefined;
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(content);
+  } catch {
+    return undefined;
+  }
+}
+
+async function anchorInventory(skillRoot: string, files: FileRecord[]): Promise<AnchorRecord[]> {
+  const anchors: AnchorRecord[] = [];
+  for (const anchor of anchorPatterns) {
+    const occurrences: Array<{ path: string; lines: number[] }> = [];
+    for (const file of files) {
+      const content = textContent(await readFile(resolve(skillRoot, file.path)));
+      if (content === undefined) continue;
+      const lines = content.split(/\r?\n/);
+      const matchingLines = lines
+        .map((line, index) => {
+          anchor.pattern.lastIndex = 0;
+          return anchor.pattern.test(line) ? index + 1 : undefined;
+        })
+        .filter((line): line is number => line !== undefined);
+      if (matchingLines.length > 0) occurrences.push({ path: file.path, lines: matchingLines });
+    }
+    if (occurrences.length > 0) {
+      anchors.push({ id: anchor.id, disposition: anchor.disposition, occurrences });
+    }
+  }
+  return anchors;
+}
+
+function parseArgs(): { verify: boolean; source?: string; revision?: string } {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === "--verify") return { verify: true };
+  const sourceIndex = args.indexOf("--source");
+  const revisionIndex = args.indexOf("--revision");
+  if (sourceIndex < 0 || revisionIndex < 0 || !args[sourceIndex + 1] || !args[revisionIndex + 1]) {
+    throw new Error("usage: sync-skills.ts --source <aili-workflows-root> --revision <40-char-sha> | --verify");
+  }
+  return { verify: false, source: resolve(args[sourceIndex + 1]), revision: args[revisionIndex + 1] };
+}
+
+async function verifySnapshot(): Promise<void> {
+  const lock = JSON.parse(await readFile(LOCK, "utf8")) as LockFile;
+  const compatibility = JSON.parse(await readFile(COMPATIBILITY, "utf8")) as {
+    source: { commit: string; contentHash: string };
+    records: Array<Record<string, unknown> & { name: string; sourceHash: string }>;
+  };
+  const files = await collectFiles(SNAPSHOT);
+  const actualHash = aggregateHash(files);
+  const expectedFiles = JSON.stringify(lock.files);
+  const actualFiles = JSON.stringify(files);
+  if (actualFiles !== expectedFiles || actualHash !== lock.contentHash) {
+    throw new Error("generated skill snapshot drifted from upstream/aili-workflows.lock.json");
+  }
+  if (compatibility.source.commit !== lock.commit || compatibility.source.contentHash !== lock.contentHash) {
+    throw new Error("skill compatibility source does not match the lock");
+  }
+  const expectedSkills = new Map(lock.skills.map((skill) => [skill.name, skill.sourceHash]));
+  const seen = new Set<string>();
+  for (const record of compatibility.records) {
+    if (seen.has(record.name)) throw new Error(`duplicate compatibility record: ${record.name}`);
+    seen.add(record.name);
+    if (expectedSkills.get(record.name) !== record.sourceHash) {
+      throw new Error(`compatibility source hash mismatch: ${record.name}`);
+    }
+    for (const field of [
+      "sourcePath",
+      "requiredCapabilities",
+      "backendAnchors",
+      "adapterOwner",
+      "verification",
+      "status",
+      "reason",
+      "unverified",
+    ]) {
+      if (!(field in record)) throw new Error(`missing compatibility field ${field}: ${record.name}`);
+    }
+  }
+  const missing = [...expectedSkills.keys()].filter((name) => !seen.has(name));
+  const unknown = [...seen].filter((name) => !expectedSkills.has(name));
+  if (missing.length || unknown.length) {
+    throw new Error(`compatibility coverage mismatch; missing=${missing.join(",")} unknown=${unknown.join(",")}`);
+  }
+  console.log(`PASS: ${lock.skillCount} skills and ${lock.fileCount} files match ${lock.commit}`);
+}
+
+async function synchronize(source: string, revision: string): Promise<void> {
+  if (!/^[0-9a-f]{40}$/.test(revision)) throw new Error("revision must be a lowercase 40-character SHA");
+  const head = git(source, ["rev-parse", "HEAD"]);
+  const status = git(source, ["status", "--porcelain", "--untracked-files=all"]);
+  const repositoryTree = git(source, ["rev-parse", "HEAD^{tree}"]);
+  const skillTree = git(source, ["rev-parse", "HEAD:.agents/skills"]);
+  const synchronizedAt = git(source, ["show", "-s", "--format=%cI", "HEAD"]);
+  const origin = git(source, ["remote", "get-url", "origin"]);
+  if (head !== revision) throw new Error(`source HEAD ${head} does not match ${revision}`);
+  if (status) throw new Error("source repository is dirty; synchronization refused");
+  if (origin.replace(/\.git$/, "") !== REPOSITORY.replace(/\.git$/, "")) {
+    throw new Error(`unexpected source origin: ${origin}`);
+  }
+  try {
+    await lstat(SNAPSHOT);
+    throw new Error("skills/ already exists; verify it and use a separately approved replacement operation");
+  } catch (error) {
+    if (error instanceof Error && !error.message.includes("ENOENT")) throw error;
+  }
+
+  const sourceSkillRoot = resolve(source, ".agents/skills");
+  const upstreamCapabilities = JSON.parse(
+    await readFile(resolve(source, "manifests/skill-capabilities.json"), "utf8"),
+  ) as {
+    profiles: Record<string, { requiredCapabilities: string[]; optionalCapabilities: string[] }>;
+    assignments: Array<{ profile: string; skills: string[] }>;
+  };
+  const profileBySkill = new Map<string, string>();
+  for (const assignment of upstreamCapabilities.assignments) {
+    for (const skill of assignment.skills) {
+      if (profileBySkill.has(skill)) throw new Error(`duplicate upstream capability assignment: ${skill}`);
+      profileBySkill.set(skill, assignment.profile);
+    }
+  }
+
+  const files = await collectFiles(sourceSkillRoot);
+  const skillNames = (await readdir(sourceSkillRoot, { withFileTypes: true }))
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort((left, right) => left.localeCompare(right));
+  if (skillNames.length !== profileBySkill.size || skillNames.some((name) => !profileBySkill.has(name))) {
+    throw new Error("upstream skill directories and capability assignments are not bijective");
+  }
+
+  const skills: LockFile["skills"] = [];
+  const records = [];
+  for (const name of skillNames) {
+    const skillFiles = files
+      .filter((file) => file.path === name || file.path.startsWith(`${name}/`))
+      .map((file) => ({ ...file, path: file.path.slice(name.length + 1) }));
+    const sourceHash = skillHash(skillFiles);
+    const profileName = profileBySkill.get(name)!;
+    const profile = upstreamCapabilities.profiles[profileName];
+    if (!profile) throw new Error(`missing upstream capability profile: ${profileName}`);
+    const markdown = await readFile(resolve(sourceSkillRoot, name, "SKILL.md"), "utf8");
+    const anchors = await anchorInventory(resolve(sourceSkillRoot, name), skillFiles);
+    const optional = ["web-research", "browser-qa", "memory", "artifact-runtime"].includes(profileName);
+    skills.push({ name, sourceHash, files: skillFiles.map((file) => file.path) });
+    records.push({
+      name,
+      sourcePath: `.agents/skills/${name}`,
+      sourceHash,
+      files: skillFiles,
+      triggers: {
+        description: parseDescription(markdown),
+        nearMissDeclared: /do not|don't|near miss|仅当|不要|不负责/i.test(markdown),
+        stopOutcomes: stopOutcomes(markdown),
+      },
+      backendAnchors: anchors,
+      requiredCapabilities: profile.requiredCapabilities,
+      optionalCapabilities: profile.optionalCapabilities,
+      canonicalChange: "none in aili-pi; consume the pinned upstream body without semantic transformation",
+      adapterOwner: optional ? `optional-pack:${profileName}` : `planned:aili-pi:${profileName}`,
+      verification: ["snapshot-hash:verified", "pi-discovery:pending", "pi-behavior:pending"],
+      status: optional ? "optional" : "blocked",
+      reason: optional
+        ? `The ${profileName} capability is not bundled until its optional provider is verified.`
+        : `The required ${profileName} Pi adapter has not yet passed behavior verification.`,
+      unverified: ["Pi discovery and behavior evidence are pending later BUILD packages."],
+    });
+  }
+
+  const lock: LockFile = {
+    schemaVersion: 1,
+    repository: REPOSITORY,
+    commit: revision,
+    repositoryTree,
+    skillTree,
+    skillRoot: ".agents/skills",
+    skillCount: skillNames.length,
+    fileCount: files.length,
+    contentHash: aggregateHash(files),
+    synchronizedAt,
+    files,
+    skills,
+  };
+  const compatibility = {
+    schemaVersion: 1,
+    source: {
+      repository: REPOSITORY,
+      commit: revision,
+      tree: skillTree,
+      contentHash: lock.contentHash,
+    },
+    allowedStatuses: ["native", "adapted", "optional", "blocked"],
+    records,
+  };
+
+  const stage = resolve(ROOT, `.tmp/sync-skills-${process.pid}`);
+  await rm(stage, { recursive: true, force: true });
+  await mkdir(dirname(stage), { recursive: true });
+  await cp(sourceSkillRoot, stage, { recursive: true, preserveTimestamps: false });
+  await mkdir(dirname(LOCK), { recursive: true });
+  await mkdir(dirname(COMPATIBILITY), { recursive: true });
+  await writeFile(`${LOCK}.tmp`, `${JSON.stringify(lock, null, 2)}\n`, { flag: "wx" });
+  await writeFile(`${COMPATIBILITY}.tmp`, `${JSON.stringify(compatibility, null, 2)}\n`, { flag: "wx" });
+  await rename(stage, SNAPSHOT);
+  await rename(`${LOCK}.tmp`, LOCK);
+  await rename(`${COMPATIBILITY}.tmp`, COMPATIBILITY);
+  await verifySnapshot();
+}
+
+const args = parseArgs();
+if (args.verify) {
+  await verifySnapshot();
+} else {
+  await synchronize(args.source!, args.revision!);
+}

package/scripts/validate-runtime.ts

@@ -0,0 +1,11 @@
+import { validateRegistry, validateStableRelease } from "../src/runtime/registry.ts";
+
+const release = process.argv.includes("--release");
+const errors = release ? await validateStableRelease() : await validateRegistry();
+if (errors.length > 0) {
+  console.error(`${release ? "stable release" : "registry"} validation failed (${errors.length})`);
+  for (const error of errors) console.error(`- ${error}`);
+  process.exitCode = 1;
+} else {
+  console.log(`${release ? "stable release" : "registry"} validation passed`);
+}

package/skills/academic-paper-review/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: academic-paper-review
+description: Review a single academic paper, preprint, DOI, arXiv link, or user-provided PDF/text with source-grounded critique. Use for paper summaries, methodology review, novelty checks, reproducibility concerns, or "review this paper" requests; do not use for multi-paper surveys, systematic literature reviews, citation management, or implementation from a paper.
+---
+
+# Academic Paper Review
+
+## Purpose
+
+Produce a careful, evidence-grounded review of one academic work. The output should help the user understand what the paper claims, how it supports those claims, what is novel, what is weak, and how much confidence to place in the result.
+
+## When to Use
+
+Use for:
+
+- reviewing one paper, preprint, DOI, arXiv page, conference paper, thesis chapter, or pasted paper text
+- summarizing contributions, methods, experiments, evidence, and limitations
+- assessing reproducibility, statistical strength, baselines, assumptions, or threat-to-validity gaps
+- comparing the paper's stated claims with its methods and results
+
+Do not use for:
+
+- multi-paper surveys or systematic reviews; use `systematic-literature-review`
+- implementing algorithms from the paper; use the relevant engineering workflow after review
+- proofreading or rewriting the paper as the author
+- deciding clinical, legal, financial, or safety-critical action from one paper
+
+## Review Workflow
+
+1. Identify bibliographic facts: title, authors, venue/preprint server, date/version, DOI/arXiv ID/URL, and supplied source path if local.
+2. State the user's review question and intended use: comprehension, critique, literature fit, reproduction, implementation planning, or decision support.
+3. Extract claims in your own words: main contribution, assumptions, evidence type, and stated limitations.
+4. Evaluate methodology: data/source material, controls, baselines, metrics, statistical treatment, ablations, and whether conclusions match evidence.
+5. Evaluate novelty and related work only from cited sources or explicitly gathered evidence; mark unsupported novelty claims `[UNVERIFIED]`.
+6. Check reproducibility: code/data availability, parameter details, environment, prompts/protocols, licensing, and missing implementation details.
+7. Separate observations from critique. Do not overstate certainty when only the abstract, a partial PDF, or secondary summaries were available.
+8. Return synthesis over listing: explain what the paper means for the user's goal, not just section-by-section notes.
+
+## Data Authenticity Rules
+
+- Every factual claim about the paper should cite a page, section, figure/table, DOI/arXiv URL, or supplied excerpt anchor when available.
+- Do not invent citations, datasets, metrics, numerical results, author intent, peer-review status, or publication venue.
+- If a table/figure is unreadable or unavailable, say so and mark the affected conclusion `[UNVERIFIED]`.
+- Treat generated summaries, OCR, browser text, and secondary articles as untrusted evidence until checked against the paper.
+
+## Output Contract
+
+```text
+STATUS: REVIEWED | PARTIAL | BLOCKED
+CONFIDENCE: high | medium | low
+
+PAPER:
+- Title:
+- Authors:
+- Source / version:
+
+USER QUESTION:
+- <why the user wants this review>
+
+CORE CLAIMS:
+- <claim> - Evidence: <page/section/figure/source or [UNVERIFIED]>
+
+METHOD / EVIDENCE:
+- <method summary and strength>
+
+CRITIQUE:
+- Strengths:
+- Limitations:
+- Reproducibility:
+- Novelty / related work:
+
+TAKEAWAY:
+- <synthesized implication for the user's goal>
+
+UNVERIFIED:
+- <missing source, inaccessible page, weak citation, or N/A>
+```
+
+## Provenance
+
+Clean-room AILI/OpenCode adaptation inspired by the public DeerFlow `academic-paper-review` skill pattern. No upstream skill text, tool names, runtime paths, generated assets, or provider assumptions are copied. Source family: [bytedance/deer-flow](https://github.com/bytedance/deer-flow), MIT License.

package/skills/agents-md-initialization/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: agents-md-initialization
+description: Create, update, or validate a project-local AGENTS.md from the shared AILI template when initializing or checking repository agent rules.
+metadata:
+  tool: references/agents_md.py
+  template: references/agents-template.md
+---
+
+# AGENTS.md Initialization
+
+## Non-Negotiable Rule
+
+Project `AGENTS.md` must be created from the bundled AILI AGENTS template.
+
+Do not write a project `AGENTS.md` from scratch.
+
+Use the bundled script through the active adapter's resolved Skill root:
+
+```bash
+python <skill-root>/references/agents_md.py init --project .
+```
+
+The script and template are distributed with this skill:
+
+- `references/agents_md.py`
+- `references/agents-template.md`
+
+If this skill is being run from a repository checkout rather than an installed adapter-managed Skill, use the repository-local path:
+
+```bash
+python .agents/skills/agents-md-initialization/references/agents_md.py init --project .
+```
+
+## Commands
+
+Initialize a project-local `AGENTS.md`:
+
+```bash
+python <skill-root>/references/agents_md.py init --project .
+```
+
+Update an existing generated project `AGENTS.md` against the current template-managed content:
+
+```bash
+python <skill-root>/references/agents_md.py update --project .
+```
+
+Check template compliance:
+
+```bash
+python <skill-root>/references/agents_md.py check --project .
+```
+
+If the adapter-resolved Skill root is unavailable but the current repository contains this skill, replace the path prefix with `.agents/skills/agents-md-initialization/`.
+
+## Workflow
+
+1. Run `init` when the target project has no `AGENTS.md`.
+2. If `AGENTS.md` already exists, do not overwrite it silently. Use `update` for template-managed compatibility updates, or ask before using `init --strategy backup-overwrite`.
+
+   🛑 **STOP before overwrite or backup-overwrite:** show the existing path, state that project-local content may be replaced outside managed blocks, and wait for explicit human approval.
+
+3. Inspect the repository and fill only project-specific sections:
+   - `Project Overview`
+   - `Setup Commands`
+   - `Architecture and Project Structure`
+   - `Project-Specific Rules`
+   - `Project-Specific Testing and Artifact Placement`
+   - `Local Overrides`
+4. Do not copy broad global workflow/safety rules into the project file unless the project intentionally strengthens or specializes them.
+5. Check CodeGraph readiness only for the exact current repository root after confirming it:
+   - run or request `codegraph status` for the target project
+   - if CodeGraph is not initialized, ask whether to run `codegraph init -i` for that exact one root; approval is per-root and is not inferred from broad or neighboring-root approval
+   - if approved, run `codegraph init -i` and then `codegraph status`
+   - if CodeGraph is unavailable, skipped, or not approved, report it as a non-blocking follow-up
+   - refuse batch/multi-repository initialization even under broad approval, and do not run `openspec init` as part of this flow
+   - treat CodeGraph as optional discovery only; stale/noisy/unavailable results fall back to ordinary search/read, every final file must still be read, and CodeGraph has no lifecycle/completion authority
+6. Run `check` before completion.
+
+## Fallbacks and Stop Conditions
+
+| Trigger condition | First response | If still unresolved |
+|---|---|---|
+| `references/agents-template.md` is missing or unreadable | Stop and report the expected bundled template path; do not hand-write `AGENTS.md` | Ask the user to restore/reinstall the skill or provide an approved template source |
+| `references/agents_md.py` is missing or not executable by Python | Stop and report the expected bundled script path and command attempted | Ask the user to restore/reinstall the skill; do not create a replacement script in the target project |
+| Installed skill path is unavailable but a repository checkout is present | Use `.agents/skills/agents-md-initialization/references/agents_md.py` from the checkout | If neither installed nor repo-local bundled script exists, stop and ask for the AILI workflow checkout path |
+| Existing `AGENTS.md` has unrecognized local content outside managed blocks | Prefer `update`; summarize preserved local sections before editing | Require explicit approval before any backup-overwrite strategy |
+| CodeGraph is not installed, unavailable, or user declines initialization | Report CodeGraph as skipped/unavailable/not approved | Do not block `AGENTS.md` completion; do not claim code-map coverage |
+| `check` fails after init/update | Report the failing output and inspect only the relevant sections | Do not claim completion until `check` passes or the failure is marked unresolved |
+
+## CI / Pre-Commit Gate
+
+Target projects should add a lightweight check when practical:
+
+```bash
+python <skill-root>/references/agents_md.py check --project .
+```
+
+For `Makefile` projects:
+
+```makefile
+check-agents:
+	python "<skill-root>/references/agents_md.py" check --project .
+```
+
+For pre-commit hooks:
+
+```bash
+#!/usr/bin/env bash
+python "<skill-root>/references/agents_md.py" check --project .
+```
+
+## Verification
+
+Report:
+
+- whether `init`, `update`, or `check` was used
+- whether an existing `AGENTS.md` was backed up
+- which project-specific sections were filled
+- CodeGraph status: initialized / initialized this run / skipped / unavailable / not approved
+- the final `check` result

package/skills/agents-md-initialization/references/agents-template.md

@@ -0,0 +1,83 @@
+<!-- AILI_AGENTS_TEMPLATE_VERSION: 2 -->
+<!-- AILI_AGENTS_TEMPLATE_SOURCE: templates/AGENTS.md -->
+<!-- AILI_AGENTS_TEMPLATE_MODE: generated-project-local-file -->
+
+# AGENTS.md
+
+This file is the project-level instruction contract for AI coding agents working in this repository.
+
+It contains project facts, local commands, local artifact placement, and repository-specific exceptions. Reusable workflow and safety invariants are installed globally by `rose-aili` from `templates/opencode-global-AGENTS.md`.
+
+Do not copy broad global operating rules into this file unless this project intentionally overrides or strengthens them.
+
+## Project Overview
+
+<!-- Fill this section during initialization. Use facts from repository files only. Do not invent missing details. -->
+
+- Project purpose: TODO
+- Primary language/runtime: TODO
+- Package manager: TODO
+- Main application entry points: TODO
+- Main test framework: TODO
+- Important directories: TODO
+- Generated/build output directories: TODO
+- Deployment/runtime environment: TODO
+
+## Setup Commands
+
+<!-- Fill with verified commands from package manifests, README, docs, Makefile, CI, or equivalent project files. Use "unknown" only when the repository does not provide enough evidence. -->
+
+- Install dependencies: TODO
+- Start development server: TODO
+- Build: TODO
+- Lint: TODO
+- Typecheck: TODO
+- Test all: TODO
+- Test focused: TODO
+- Format: TODO
+- Clean: TODO
+
+## Architecture and Project Structure
+
+<!-- Summarize only facts discovered from repository files. Do not invent architecture. -->
+
+- `src/`: TODO
+- `tests/`: TODO
+- `docs/`: TODO
+- `scripts/`: TODO
+- Configuration files: TODO
+- CI/CD files: TODO
+- Generated files: TODO
+- External integrations: TODO
+
+## Project-Specific Rules
+
+<!-- Add rules that are specific to this repository. Do not add personal preferences, temporary task notes, or generic advice. -->
+
+- TODO
+
+## Project-Specific Testing and Artifact Placement
+
+<!-- Record repository-specific test locations and artifact placement decisions. Keep global verification discipline in the global AGENTS file. -->
+
+- Unit tests: TODO
+- Integration tests: TODO
+- CLI tests: TODO
+- API / contract tests: TODO
+- GUI / browser / Playwright tests: TODO
+- Test fixtures: TODO
+- Snapshots / golden files: TODO
+- Test reports / traces / screenshots: TODO
+- Temporary test output: TODO
+
+Rules:
+
+- Do not place new test files in the repository root unless this section explicitly allows it.
+- Unless the user explicitly requests an external or temporary-only artifact, user-visible test files, test plans, reports, traces, screenshots, generated fixtures, golden files, and verification artifacts must be written inside the repository at a project-defined path or after a placement decision.
+- If a new test category is introduced, ask the user for its repository-local location once, then record the chosen convention here.
+
+## Local Overrides
+
+<!-- Optional. Add local overrides only when this repository needs to strengthen or specialize the global AGENTS rules. Do not weaken global safety, evidence, git, security, or completion rules. -->
+
+- None documented.