@goodtek/vibeops 0.2.0

package/dist/status/collector.js

@@ -0,0 +1,103 @@
+import { basename } from "node:path";
+import { isDirectory, isFile, pathExists } from "../lib/filesystem.js";
+import { readConfig } from "../lib/config.js";
+import { readGitInfo } from "../lib/git.js";
+import { getNotionTokenSource } from "../lib/notion-env.js";
+import { readPackageJson, } from "../lib/package-json.js";
+import { countTasks, pickNextTask, scanTasks } from "../lib/task.js";
+import { projectPaths } from "../lib/paths.js";
+import { DEFAULT_GITHUB_CONFIG, } from "../types/config.js";
+async function presenceCheck(label, path, required, asDir) {
+    const present = asDir ? await isDirectory(path) : await isFile(path);
+    return { label, path, present, required };
+}
+function snapshotNotion(notion, token) {
+    const projects = (notion?.projectsTargetId ?? "").length > 0 ||
+        (notion?.projectsDatabaseId ?? "").length > 0;
+    const tasks = (notion?.tasksTargetId ?? "").length > 0 ||
+        (notion?.tasksDatabaseId ?? "").length > 0;
+    return {
+        enabled: notion?.enabled ?? false,
+        hasToken: token.hasToken,
+        tokenSource: token.source,
+        hasProjectsTarget: projects,
+        hasTasksTarget: tasks,
+    };
+}
+function snapshotGithub(github) {
+    const g = github ?? DEFAULT_GITHUB_CONFIG;
+    return {
+        enabled: g.enabled,
+        mode: g.enabled ? g.mode : "",
+        owner: g.owner,
+        repo: g.repo,
+        remote: g.remote,
+        url: g.url,
+    };
+}
+function pickBinName(pkg) {
+    const bin = pkg.bin;
+    if (typeof bin === "string") {
+        return basename(bin).replace(/\.[A-Za-z0-9]+$/, "");
+    }
+    if (bin !== null && typeof bin === "object") {
+        const keys = Object.keys(bin);
+        if (keys.length > 0)
+            return keys[0];
+    }
+    return "";
+}
+function snapshotPackage(pkg) {
+    if (pkg === null) {
+        return { exists: false, name: "", version: "", bin: "" };
+    }
+    const data = pkg.data;
+    const name = typeof data.name === "string" ? data.name : "";
+    const version = typeof data.version === "string"
+        ? (data.version ?? "")
+        : "";
+    return { exists: true, name, version, bin: pickBinName(data) };
+}
+export async function collectStatus(cwd) {
+    const paths = projectPaths(cwd);
+    const config = await readConfig(paths.root);
+    const checks = [
+        await presenceCheck(".vibeops.json", paths.config, true, false),
+        await presenceCheck("AGENTS.md", paths.agentsMd, true, false),
+        await presenceCheck(".cursor/rules/", paths.cursorRules, true, true),
+        await presenceCheck("docs/project/", paths.docsProject, true, true),
+        await presenceCheck("docs/tasks/", paths.docsTasks, true, true),
+        await presenceCheck("docs/logs/", paths.docsLogs, false, true),
+        await presenceCheck(".vibeops/agents/", paths.vibeopsAgents, true, true),
+        await presenceCheck(".vibeops/prompts/", paths.vibeopsPrompts, false, true),
+        await presenceCheck(".vibeops/workflows/", paths.vibeopsWorkflows, false, true),
+        await presenceCheck(".vibeops.env.example", paths.envExample, false, false),
+    ];
+    const missingRequired = checks.filter((c) => c.required && !c.present);
+    const tasks = (await pathExists(paths.docsTasks))
+        ? await scanTasks(paths.docsTasks)
+        : [];
+    const taskCounts = countTasks(tasks);
+    const nextTask = pickNextTask(tasks);
+    const git = await readGitInfo(paths.root);
+    const tokenProbe = await getNotionTokenSource(paths.root);
+    const notion = snapshotNotion(config?.notion, tokenProbe);
+    const github = snapshotGithub(config?.github);
+    const pkg = await readPackageJson(paths.root);
+    const packageSnapshot = snapshotPackage(pkg);
+    const isVibeopsProject = config !== null && missingRequired.length === 0;
+    return {
+        cwd: paths.root,
+        isVibeopsProject,
+        config,
+        checks,
+        missingRequired,
+        tasks,
+        taskCounts,
+        nextTask,
+        git,
+        notion,
+        github,
+        package: packageSnapshot,
+    };
+}

package/dist/status/format.js

@@ -0,0 +1,177 @@
+import { relative } from "node:path";
+import { bold, cyan, dim, green, log, red, yellow } from "../lib/logger.js";
+function relOrAbs(root, p) {
+    const r = relative(root, p);
+    if (r === "")
+        return ".";
+    if (r.startsWith(".."))
+        return p;
+    return r;
+}
+function statusBadge(value, label) {
+    if (value === 0)
+        return dim(`${label}:0`);
+    return `${label}:${value}`;
+}
+function pad(label, width) {
+    if (label.length >= width)
+        return label;
+    return label + " ".repeat(width - label.length);
+}
+function tokenLine(report) {
+    if (!report.notion.hasToken)
+        return red("missing");
+    return `${green("configured")} ${dim(`(${report.notion.tokenSource})`)}`;
+}
+function targetLine(present) {
+    return present ? green("configured") : red("missing");
+}
+function notionHint(report) {
+    if (!report.notion.enabled)
+        return "run `vibeops notion init`";
+    if (!report.notion.hasToken)
+        return "set NOTION_TOKEN in `.vibeops.env`";
+    if (!report.notion.hasProjectsTarget || !report.notion.hasTasksTarget) {
+        return "run `vibeops notion init` to pick a Projects / Tasks DB";
+    }
+    return "run `vibeops notion test`";
+}
+export function printHuman(report) {
+    log.info(bold("Project"));
+    if (report.config) {
+        log.info(`  name           ${report.config.name}`);
+        log.info(`  vibeopsVersion ${report.config.vibeopsVersion}`);
+        log.info(`  schemaVersion  ${String(report.config.schemaVersion)}`);
+        log.info(`  createdAt      ${report.config.createdAt}`);
+    }
+    else {
+        log.info(`  ${red("(no .vibeops.json — not a VibeOps project)")}`);
+    }
+    log.blank();
+    log.info(bold("Installation"));
+    for (const c of report.checks) {
+        const tag = c.present
+            ? green("✓")
+            : c.required
+                ? red("✗")
+                : yellow("·");
+        const reqHint = c.required ? "" : dim(" (optional)");
+        log.info(`  ${tag} ${c.label}${reqHint}  ${dim(relOrAbs(report.cwd, c.path))}`);
+    }
+    if (report.missingRequired.length > 0) {
+        log.blank();
+        log.warn(`${report.missingRequired.length} required path(s) missing.`);
+    }
+    log.blank();
+    log.info(bold("Tasks"));
+    const { total, planned, in_progress, review, blocked, done } = report.taskCounts;
+    log.info(`  ${cyan(`total:${total}`)}  ${statusBadge(planned, "planned")}  ${statusBadge(in_progress, "in_progress")}  ${statusBadge(review, "review")}  ${statusBadge(blocked, "blocked")}  ${statusBadge(done, "done")}`);
+    if (report.nextTask) {
+        log.info(`  next  ${report.nextTask.id} — ${report.nextTask.title || dim("(no title)")}  ${dim(`[${report.nextTask.status}]`)}`);
+    }
+    else if (total === 0) {
+        log.info(`  ${dim("no TASK files yet — run `vibeops task generate`")}`);
+    }
+    else {
+        log.info(`  ${dim("all tasks done")}`);
+    }
+    log.blank();
+    log.info(bold("Git"));
+    if (!report.git.isRepo) {
+        log.info(`  ${dim("not a git repository")}`);
+    }
+    else {
+        if (report.git.state === "unborn") {
+            log.info(`  branch  ${report.git.branch ?? "(unknown)"} ${dim("(unborn, no commits yet)")}`);
+        }
+        else if (report.git.state === "detached") {
+            log.info(`  branch  ${dim("(detached)")}${report.git.branch ? ` ${report.git.branch}` : ""}`);
+        }
+        else {
+            log.info(`  branch  ${report.git.branch ?? dim("(unknown)")}`);
+        }
+        log.info(`  status  ${report.git.dirty ? yellow("dirty") : green("clean")}`);
+        if (report.git.state === "unborn") {
+            log.info(`  hint    create the first commit or run ${cyan("`vibeops init --git --initial-commit`")}`);
+        }
+    }
+    log.blank();
+    // Notion: enabled / token / projects target / tasks target / hint.
+    // We intentionally do NOT print legacy env names (NOTION_API_KEY,
+    // NOTION_PROJECT_DB, NOTION_TASK_DB) — modern VibeOps only uses
+    // NOTION_TOKEN + notion.{projectsTargetId,tasksTargetId}.
+    log.info(bold("Notion"));
+    const notionLabelWidth = 16; // "projects target"
+    log.info(`  ${pad("enabled", notionLabelWidth)} ${report.notion.enabled ? green("yes") : dim("no")}`);
+    log.info(`  ${pad("token", notionLabelWidth)} ${tokenLine(report)}`);
+    log.info(`  ${pad("projects target", notionLabelWidth)} ${targetLine(report.notion.hasProjectsTarget)}`);
+    log.info(`  ${pad("tasks target", notionLabelWidth)} ${targetLine(report.notion.hasTasksTarget)}`);
+    log.info(`  ${pad("hint", notionLabelWidth)} ${dim(notionHint(report))}`);
+    log.blank();
+    log.info(bold("GitHub"));
+    const githubLabelWidth = 11; // "owner/repo"
+    if (!report.github.enabled) {
+        log.info(`  ${pad("enabled", githubLabelWidth)} ${dim("no")}`);
+        log.info(`  ${pad("hint", githubLabelWidth)} ${dim("run `vibeops github init`")}`);
+    }
+    else {
+        log.info(`  ${pad("enabled", githubLabelWidth)} ${green("yes")}`);
+        if (report.github.mode.length > 0) {
+            log.info(`  ${pad("mode", githubLabelWidth)} ${report.github.mode}`);
+        }
+        const slug = report.github.owner.length > 0 && report.github.repo.length > 0
+            ? `${report.github.owner}/${report.github.repo}`
+            : dim("(unknown)");
+        log.info(`  ${pad("owner/repo", githubLabelWidth)} ${slug}`);
+        log.info(`  ${pad("remote", githubLabelWidth)} ${report.github.remote.length > 0 ? report.github.remote : dim("(none)")}`);
+        log.info(`  ${pad("url", githubLabelWidth)} ${report.github.url.length > 0 ? report.github.url : dim("(none)")}`);
+    }
+    log.blank();
+    log.info(bold("Package"));
+    const pkgLabelWidth = 8; // "version"
+    if (!report.package.exists) {
+        log.info(`  ${dim("package.json missing")}`);
+    }
+    else {
+        log.info(`  ${pad("name", pkgLabelWidth)} ${report.package.name.length > 0 ? report.package.name : dim("(unset)")}`);
+        log.info(`  ${pad("version", pkgLabelWidth)} ${report.package.version.length > 0 ? report.package.version : dim("(unset)")}`);
+        log.info(`  ${pad("bin", pkgLabelWidth)} ${report.package.bin.length > 0 ? report.package.bin : dim("(none)")}`);
+    }
+    log.blank();
+    if (!report.isVibeopsProject) {
+        log.error("Not a VibeOps project — run `vibeops init` first.");
+    }
+    else {
+        log.ok("VibeOps project ready.");
+    }
+}
+export function toJson(report) {
+    return `${JSON.stringify({
+        cwd: report.cwd,
+        isVibeopsProject: report.isVibeopsProject,
+        config: report.config,
+        installation: {
+            checks: report.checks.map((c) => ({
+                label: c.label,
+                path: c.path,
+                present: c.present,
+                required: c.required,
+            })),
+            missingRequired: report.missingRequired.map((c) => c.label),
+        },
+        tasks: {
+            counts: report.taskCounts,
+            next: report.nextTask
+                ? {
+                    id: report.nextTask.id,
+                    title: report.nextTask.title,
+                    status: report.nextTask.status,
+                }
+                : null,
+        },
+        git: report.git,
+        notion: report.notion,
+        github: report.github,
+        package: report.package,
+    }, null, 2)}\n`;
+}

package/dist/types/brief.js

@@ -0,0 +1,126 @@
+export const PROJECT_BRIEF_SCHEMA_VERSION = 1;
+export const PROJECT_TYPE_CHOICES = [
+    "SaaS",
+    "Web App",
+    "CLI Tool",
+    "Browser Automation",
+    "AI Agent",
+    "Internal Tool",
+    "Other",
+];
+export const TARGET_USER_CHOICES = [
+    "Solo founders",
+    "Developers",
+    "Marketers",
+    "Small business owners",
+    "Internal team",
+    "Other",
+];
+export const MVP_FEATURE_CHOICES = [
+    "Authentication",
+    "Dashboard",
+    "Project/workspace management",
+    "Task/job creation",
+    "Background worker",
+    "Browser automation",
+    "Scheduling",
+    "Execution logs",
+    "External integrations",
+    "Other",
+];
+export const OUT_OF_SCOPE_CHOICES = [
+    "Billing",
+    "Team workspace",
+    "Mobile app",
+    "Marketplace",
+    "Advanced analytics",
+    "Enterprise SSO",
+    "Public API",
+    "Real-time collaboration",
+    "Other",
+];
+export const FRONTEND_CHOICES = [
+    "Next.js",
+    "React + Vite",
+    "None / CLI only",
+    "Not sure",
+    "Other",
+];
+export const BACKEND_CHOICES = [
+    "NestJS",
+    "Next.js API routes",
+    "Node.js Fastify",
+    "Hono",
+    "Python FastAPI",
+    "None",
+    "Not sure",
+    "Other",
+];
+export const DATABASE_CHOICES = [
+    "PostgreSQL",
+    "SQLite",
+    "MySQL",
+    "Supabase",
+    "None",
+    "Not sure",
+    "Other",
+];
+export const DB_LAYER_CHOICES = [
+    "Drizzle",
+    "Prisma",
+    "Kysely",
+    "Raw SQL",
+    "None",
+    "Not sure",
+    "Other",
+];
+export const PACKAGE_MANAGER_CHOICES = ["pnpm", "npm", "yarn", "bun"];
+export const DEPLOYMENT_TARGET_CHOICES = [
+    "VPS",
+    "Docker",
+    "Podman",
+    "Vercel",
+    "Cloudflare",
+    "AWS",
+    "Not sure",
+    "Other",
+];
+export const AUTH_REQUIREMENT_CHOICES = [
+    "Email/password",
+    "Google login",
+    "GitHub login",
+    "Magic link",
+    "Admin-only",
+    "No auth for MVP",
+    "Not sure",
+    "Other",
+];
+export const INTEGRATION_CHOICES = [
+    "Notion",
+    "GitHub",
+    "Google Drive",
+    "Gmail",
+    "Slack",
+    "Stripe",
+    "OpenAI",
+    "Anthropic",
+    "Browser / Playwright",
+    "None",
+    "Other",
+];
+export const AGENT_WORKFLOW_CHOICES = [
+    "Simple: Planner + Builder + Reviewer",
+    "Standard: Orchestrator + Planner + Builder + Reviewer + Docs",
+    "Advanced: Orchestrator + Planner + Architect + Builder + Tester + Reviewer + Docs + Recovery",
+];
+export const RISK_AREA_CHOICES = [
+    "Authentication/security",
+    "Browser automation reliability",
+    "Cost control",
+    "Scalability",
+    "Data privacy",
+    "Deployment complexity",
+    "Background jobs",
+    "AI hallucination",
+    "Other",
+];

package/dist/types/config.js

@@ -0,0 +1,17 @@
+export const VIBEOPS_CONFIG_SCHEMA_VERSION = 1;
+export const DEFAULT_NOTION_CONFIG = {
+    enabled: false,
+    projectsTargetId: "",
+    tasksTargetId: "",
+    projectsDatabaseId: "",
+    tasksDatabaseId: "",
+};
+export const DEFAULT_GITHUB_CONFIG = {
+    enabled: false,
+    mode: "gh-cli",
+    owner: "",
+    repo: "",
+    remote: "origin",
+    visibility: "",
+    url: "",
+};

package/dist/types/task.js

@@ -0,0 +1 @@
+export {};

package/dist/version.js

@@ -0,0 +1,8 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const here = dirname(fileURLToPath(import.meta.url));
+const pkgPath = join(here, "..", "package.json");
+const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+export const VERSION = pkg.version;
+export const NAME = pkg.name;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@goodtek/vibeops",
+  "version": "0.2.0",
+  "description": "Workflow rails for Cursor-based vibe coding projects.",
+  "type": "module",
+  "author": "VibeOps contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/goodtekxyz/vibeops.git"
+  },
+  "homepage": "https://github.com/goodtekxyz/vibeops#readme",
+  "bugs": {
+    "url": "https://github.com/goodtekxyz/vibeops/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "vibeops": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "cursor",
+    "ai",
+    "coding",
+    "cli",
+    "task",
+    "notion",
+    "vibeops",
+    "workflow"
+  ],
+  "dependencies": {
+    "@inquirer/prompts": "^8.4.3",
+    "@notionhq/client": "^5.20.0",
+    "commander": "^12.1.0",
+    "gray-matter": "^4.0.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4"
+  },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/cli.js",
+    "smoke": "pnpm typecheck && pnpm build && node scripts/smoke.mjs",
+    "publish:dry": "pnpm publish --dry-run --no-git-checks"
+  }
+}

package/templates/.cursor/rules/00-project-governance.mdc

@@ -0,0 +1,28 @@
+---
+description: Governance for {{PROJECT_NAME}} — source of truth, single TASK, MVP boundary.
+alwaysApply: true
+---
+
+# Project Governance
+
+## Source of truth
+
+- **`docs/project/`** and **`docs/tasks/`** take precedence. Chat history is not trusted.
+- When docs and chat disagree, align the docs **first**, then implement.
+- The human dashboard (Notion) syncs **summary, status, priority, branch, docs path, and result summary only**. Full bodies live in `docs/tasks/*.md`.
+
+## One TASK at a time
+
+- Implementation must correspond to **a single TASK**.
+- Stay inside the TASK's **Scope / Acceptance Criteria**.
+- Use the TASK ID (`TASK-NNN`) consistently across commit messages, branch names, and log entries.
+
+## Protect the MVP scope
+
+- Do **not** add features that are not listed in `docs/project/02-mvp-scope.md`.
+- "Convenience" items such as hosting, realtime sync, webhooks, and automatic LLM calls are introduced only via a dedicated TASK.
+
+## Refactors and integrations
+
+- Large refactors happen only when a dedicated TASK calls for them.
+- External integrations (Git host APIs, Notion, messengers, …) are added only when the TASK explicitly says so.

package/templates/.cursor/rules/01-agent-orchestration.mdc

@@ -0,0 +1,48 @@
+---
+description: How 8 agents in .vibeops/agents/* collaborate on a single TASK.
+alwaysApply: true
+---
+
+# Agent Orchestration
+
+This project defines 8 agents in `.vibeops/agents/*.md`. Every agent stays inside **its own role**.
+
+## Flow
+
+```
+user / PM
+   │
+   ▼
+[orchestrator]  ── picks the next TASK, calls the right agent
+   │
+   ├──▶ [planner]    idea → docs/project/{00,01,02,07}
+   ├──▶ [architect]  docs/project/{03,04}
+   ├──▶ [builder]    one TASK, code changes
+   ├──▶ [reviewer]   diff vs Acceptance Criteria
+   ├──▶ [tester]     run Test Plan → Test Result
+   ├──▶ [docs]       update 05-current-state / TASK Result / logs
+   └──▶ [recovery]   diagnose rollback (destructive actions require --confirm)
+```
+
+## How to invoke
+
+Get an agent prompt from the VibeOps CLI:
+
+```
+vibeops agent prompt <agent> <TASK-NNN>
+vibeops task prompt <TASK-NNN> --agent <agent>
+```
+
+Paste the resulting markdown directly into the Cursor chat.
+
+## Role boundaries
+
+- `builder` does not do `reviewer`'s job (self-checks are fine, but a real review is a separate call).
+- `planner` does not write code. `architect` does not decide business logic.
+- `docs` does not make code changes — documentation only.
+- No agent runs **multiple TASKs in parallel**.
+
+## Forbidden
+
+- "Not really my job but I'll just do it" — no. Call the right agent again.
+- Editing the agent definition files (`.vibeops/agents/*.md`) without a TASK that authorizes it.

package/templates/.cursor/rules/02-task-workflow.mdc

@@ -0,0 +1,38 @@
+---
+description: Task workflow — start, prompt, check, done lifecycle and dry-run discipline.
+alwaysApply: true
+---
+
+# Task Workflow
+
+## Before you start
+
+1. Read `docs/project/05-current-state.md` and identify the next TASK to run.
+2. Read the **entire** `docs/tasks/TASK-NNN-*.md` file.
+3. Keep Scope / Out of Scope / Acceptance Criteria in mind.
+4. **Search** the existing code for similar implementations and patterns (do not duplicate).
+
+## While implementing
+
+- Run **one TASK at a time**.
+- Search the existing code once more before adding new files, functions, or patterns.
+- **Every CLI command should support `--dry-run`** (or an equivalent) so the plan can be previewed without touching files, Git, or remotes.
+- Do not edit the next TASK file before the current TASK is done.
+
+## Lifecycle commands
+
+| Step       | Command                                                              |
+| ---------- | -------------------------------------------------------------------- |
+| Start      | `vibeops task start TASK-NNN`                                        |
+| Work       | `vibeops task prompt TASK-NNN --agent builder` → paste into Cursor    |
+| Check      | `vibeops task check TASK-NNN`                                        |
+| Finish     | `vibeops task done TASK-NNN` (no auto-merge)                         |
+| Roll back  | `vibeops task rollback TASK-NNN` (guidance by default, destructive paths need `--confirm`) |
+
+## Definition of done
+
+- All Acceptance Criteria pass.
+- The TASK file's **Result** and **Test Result** are non-empty.
+- `docs/project/05-current-state.md` and `docs/logs/YYYY-MM-DD.md` are updated.
+
+A TASK is not considered complete until all three updates land.

package/templates/.cursor/rules/03-git-safety.mdc

@@ -0,0 +1,30 @@
+---
+description: Git safety — branch per TASK, rollback safety, never force-push.
+alwaysApply: true
+---
+
+# Git Safety
+
+## Branch policy
+
+- One branch per TASK: `task/<task-id>-<slug>`, e.g. `task/002-init-command`.
+- At TASK start, the base branch / base commit / task branch are recorded in `.vibeops/state/tasks/TASK-NNN.json` (automatic).
+- After merge, the task branch is deleted by default (`git branch -d`). Discarding an unmerged branch goes through the rollback flow.
+
+## Commit messages
+
+- Include the TASK ID. Examples: `feat(TASK-002): vibeops init`, `docs(TASK-006): plan command spec`.
+- One commit covers only one TASK's scope.
+
+## Safety rules
+
+- `vibeops task rollback` produces **guidance by default**. Destructive Git actions run only with `--confirm`.
+- **No force-push** (especially on shared branches).
+- No automatic merge, no automatic push. A human does both explicitly.
+- `task start` refuses a dirty working tree (override with `--allow-dirty`).
+
+## Forbidden
+
+- Doing several TASKs on one branch.
+- Omitting the TASK ID from a commit message.
+- Committing directly to shared branches such as `main` / `master` — always go through the TASK branch.

package/templates/.cursor/rules/04-docs-update.mdc

@@ -0,0 +1,22 @@
+---
+description: After implementation, update three documents together.
+alwaysApply: true
+---
+
+# Docs Update
+
+Update the three documents below **together** when the implementation is done. A TASK is not considered complete until all three are updated.
+
+1. **`docs/project/05-current-state.md`** — facts only (implementation stage, paths, next TASK).
+2. **`docs/tasks/TASK-NNN-*.md`** — Status, **Result**, **Test Result**.
+3. **`docs/logs/YYYY-MM-DD.md`** — local-date filename; create the file if it does not exist. If multiple updates happen on the same day, add entries to the same file.
+
+## Tone
+
+- **Facts first**. No marketing copy, no self-praise.
+- Record the changed file paths, the commands you ran with their results, and the decisions you made.
+- A teammate (or your future self in five minutes) should grasp "where things stand" within a minute.
+
+## Chat report
+
+Follow the "Completion report" section in `AGENTS.md`.